About This Guide
This guide contains instructions for deploying Audio Weaver custom modules to SHARC target hardware. This guide specifically uses the ADI-21569-SOM EVK, but the general process should be applicable for other SHARC target hardware.
General Process Overview
The process of adding custom modules on SHARC target is similar to other platforms, but the toolchain differs. For SHARC target hardware, the Analog Devices CrossCore Embedded Studio (CCES) IDE is needed to build an Audio Weaver custom module pack library and the board support package (BSP). Using the latest version of CCES is recommended.
Dependencies
To deploy Custom Modules to the ADI-21569-SOM SHARC DSP, the following dependencies are needed:
Audio Weaver Pro
CrossCore Embedded Studio IDE
Audio Weaver Custom Module source code
ADI-21569-SOM Audio Weaver BSP
General Steps
1. Build the Audio Weaver custom module static library in CCES
2. Include the Audio Weaver custom module static library in the BSP project linker options
3. Include desired custom modules from the Audio Weaver custom module static library in the ModulesList.h file
4. Build the BSP
NOTE: Depending on the module's size, there may be linker errors, but can be resolved by removing unnecessary module's or adjusting the linker file.
CCES Environment Setup and Custom Module Library Build
CCES Workspace
Download the Analog Devices CCES IDE for SHARC processors from the Analog Devices website: CrossCore Embedded Studio (CCES).
Set up CCES workspace directory:
Figure 1: CCES Studio Launcher Workspace Directory
The default directory is fine unless another directory is preferred.
Create a new CrossCore Project. ‘File > New > CrossCore Project’:
Figure 2: New CrossCore Project
When prompted, select the CrossCore Project Wizard:
Figure 3: CrossCore Project Wizard
The standard Audio Weaver Module folder structure is pictured below:
Figure 4: Standard Audio Weaver Module Folder Structure
NOTE: Refer to the Bringing Algorithms into Audio Weaver Application Note, Developing Custom Modules: Quick Start Guide, and Developing Custom Modules: Guide more information about the standard Audio Weaver Module folder structure.
We’ll want to create the CCES Project in the ‘/projects’ folder of the Custom Module directory to keep things contained and prevent path errors. After selecting the CrossCore Project Wizard, set the CrossCore Project Name and path as below. You may have to create a new ‘SHARC’ folder in ‘/projects’:
Figure 5: SHARC CrossCore Project Folder Path
Figure 6: CCES Project Name and Location
Click ‘Next’ and choose the appropriate SHARC DSP you’re using in the next prompt. In this case, we select SHARC ADSP-21569:
Figure 7: CrossCore Project Processor Type
Click ‘Next’, and then ‘Finish’ in the next Projects and Settings prompt:
Figure 8: CrossCore Projects and Settings
Custom Module CrossCore Project Properties and Settings
Right click on the ‘SHARC’ project that we created in the previous steps, and navigate to ‘Properties’ in the context window:
Figure 9: SHARC Project Properties
Navigate to ‘C/C++ Build > Settings’ for the Release Build Configuration, and in the ‘Build Artifact’ Properties tab, and choose ‘Static Library’ for the Artifact Type:
Figure 10: Release Build Artifact Type
Navigate to ‘C/C++ Build > Settings’ for the Release Build Configuration, and in the ‘Tool Settings’ Properties tab, add the following paths to the ‘Additional include directories’:
C:\DSP Concepts\AWE Designer 8.C.2.6 Pro\AWEModules\Source\Examples\Include
C:\DSP Concepts\AWE Designer 8.C.2.6 Pro\AWEModules\Source\Examples\Include\Targets
C:\DSP Concepts\AWE Designer 8.C.2.6 Pro\Bin\Assets\module\include
Figure 11: Additional Include Directories
Click ‘Apply and Close’:
Figure 12: Apply Custom Module CrossCore Properties and Settings
It is ok to disregard these warnings if notified after applying the settings:
Figure 13: Custom Module CrossCore Project Settings Change Warning
Building the Custom Module .dlb Library
Now we must add the Custom Module C code.
NOTE: The C files to be added to the project are generated from a make_*.m script outlined in the Specifying Dependencies section of the Developing Custom Modules: Guide.
Right click on the ‘SHARC’ project in the Project Explorer tab on the left hand side of the CCES IDE window, and select to ‘Import’ from the context window:
Figure 14: Import Custom Module C Code
Select ‘File System’ from the Import Wizard and click ‘Next’:
Figure 15: Import Wizard - Import File System
Select ‘Browse’ to navigate to the directory containing the Custom Module C code:
Figure 16: Custom Module C Code Directory
The standard path that the generated C files from the Custom Module make_*.m script are placed in the ‘source’ folder of the parent Custom Module directory (<DIR>\source). Select the ‘source’ folder of the Custom Module directory as the directory to be imported from:
Figure 17: Custom Module Source Directory
Select the Custom Module C files to be added to the project, with the following import settings and click ‘Finish’:
Figure 18: Import Custom Module C Files
You should now be able to see the Custom Module C Files included in the SHARC project, in the CCES IDE Project Explorer tab:
Figure 19: Included Custom Module C Files
Right click on the SHARC project in the CCES IDE Project Explorer tab and select ‘Build Project’ to build the Custom Module .dlb library:
Figure 20: Build Custom Module .dlb Library
After building the project, you should see a Build Finished confirmation in the CCESSS IDE console:
Figure 21: Custom Module .dlb Build Finished
You should now see the Custom Module .dlb library (SHARC.dlb) under the Custom Module Project in the CCES IDE Project Explorer:
Figure 22: Built Custom Module .dlb Library
The Custom Module .dlb Library should be located in the ‘Release’ folder of the SHARC project directory:
Figure 23: SHARC Release Build Folder
ADI-21569-SOM BSP
Importing the BSP to CCES IDE
From the top CCES IDE menu bar, select ‘File > Import’:
Figure 24: BSP Project Import
Select ‘General > Existing Projects into Workspace’ from the pop-up CCES IDE Import Wizard:
Figure 25: Import Existing Projects Into Workspace
Select the ‘Browse’ button to locate the ADI-21569-SOM BSP Project directory:
Figure 26: Browse for ADI-21569-SOM BSP Directory
The ADI-21569-SOM BSP should be located in the ‘<DIR>\awe8-bsp-adi-21569-som\SampleApp\21569_SOM\Build\CCES’ folder. Select the ‘CCES’ folder:
Figure 27: CCES ADI-21569-SOM BSP Folder
Select the ‘21569_SOM_BSP’ to be imported and click ‘Finish’:
Figure 28: 21569_SOM_BSP
You should now see the ‘21569_SOM_BSP’ in the Project Explorer in the left hand side of the CCES IDE window:
Figure 29: 21569_SOM_BSP Imported
Linking Custom Module .dlb Library to BSP
Copy the SHARC.dlb Library we built in Section 3.3 to the ‘<DIR>\awe8-bsp-adi-21569-som\AWECore\Lib\CCES’ folder, such that it shares a common path with AWECore.dlb:
Figure 30: Copy SHARC.dlb Library
Right click on the ‘21569_SOM_BSP’ project in the CCES IDE Project Explorer and navigate to ‘Properties’ in the context menu:
Figure 31: 21569_SOM_BSP Properties
In the ‘C/C++ Build > Settings’ Debug Build Configuration Tool Settings tab, under ‘CrossCore SHARC Linker > General’, click on the ‘+’ button in the ‘Additional libraries and object files’ pane:
Figure 32: Add Additional Libraries and Object Files to CrossCore SHARC Linker
Since we copied the SHARC.dlb library to the same path as the AWECore.dlb library in a previous step, we can simply type in ‘SHARC.dlb’ in the File Path input bar:
Figure 33: Add SHARC.dlb to CrossCore SHARC Linker
Click ‘Ok’ and then ‘Apply and Close’.
Adding Custom Module Objects to ModuleList.h
Navigate to the ‘<DIR>/awe8-bsp-adi-21569-som/SampleApp/21569_SOM/Source’ folder and open ModuleList.h for editing:
Figure 34: ModuleList.h
The ModuleList.h header file contains an array LISTOFCLASSOBJECTS that represents the list of all modules to be linked into the BSP build, so to use our new custom modules, we must add their symbols to this array.
NOTE: For more information about ModuleList.h and its functionality, refer to the Optimization section of the AWE Core 8 Integration Guide.
We must edit ModuleList.h in two places:
Declare the custom module symbols as extern const int variables
Add the custom modules to the preprocessor array
Also notice the naming convention. This naming convention must be followed to successfully link the new module classes.
First, we add the symbol variables:
Figure 35: ModuleList.h Symbol Variables
Next, add the new module variables to the LISTOFLCASSOBJECTS array:
Figure 36:ModuleList.h LISTOFCLASSOBJECTS Array
Save the edited ModuleList.h file.
Build the BSP
Right click on the ‘21569_SOM_BSP’ in the CCES IDE Project Explorer, and select ‘Build Project’ from the context menu:
Figure 37: Build 21569_SOM_BSP Project
NOTE: If you get an error message about opening the ‘ezkit21569_initcode.dxe’ file, it may be because you are using a different version of CCES than the version the original BSP was built with:
Figure 38: Unable to Open File: ezkit21569_initcode.dxe
To remedy this, right click on the ‘21569_SOM_BSP’ in the CCES IDE Project Explorer, and select ‘Properties’ from the context menu:
Figure 39: 21569_SOM_BSP Properties
Navigate to the ‘C/C++ Build > Settings’ Debug Build Configuration Tool Settings tab, under ‘CrossCore SHARC Loader > Initialization’, and edit the Initialization file path to match the CCES IDE version you are using:
Figure 40: CrossCore SHARC Loader CCES IDE Version Initialization File Path
The ‘CrossCore Embedded Studio x.xx.x’ needs to match the CCES IDE you are using.
Click ‘Apply and Close’ once correctly edited (if applicable).
Right click on the ‘21569_SOM_BSP’ project in the Project Explorer and select ‘Build Project’ from the context menu:
Figure 41: Build 21569_SOM_BSP
Upon successful completion of the BSP image build, you should see confirmation in the CCES IDE console window:
Figure 42: 21569_SOM_BSP Build Success
The ‘21569_SOM_BSP.ldr’ flash image will be placed in the ‘<DIR>\awe8-bsp-adi-21569-som\SampleApp\21569_SOM\Bin’ directory:
Figure 43: 21569_SOM_BSP.ldr
Follow the ‘Audio-Weaver ADSP-21569 SOM Target Users Guide.pdf’ document to flash your ADI-21569-SOM EVK, connect to Audio Weaver, and use your Custom Module(s) on the embedded SHARC DSP target hardware.