Deploying Custom Modules on AWECoreOS Linux Targets

Overview

You may wish to deploy custom modules onto a base AWECoreOS that you received from DSP Concepts. This application note will show you how to do so using both the Raspberry Pi and NXP PicoPi as example target devices. The procedure is no different for either device and should work with any properly configured modern Linux.

Requirements

• Linux-based device supporting AWECoreOS

• Standard build tools installed (gcc, make, cmake)

Procedure to compile and use sample module

1. Copy the supplied tutorial_module.zip file to your AWECoreOS enabled device.

tutorial_module.zip

2. Extract the contents using the unzip command

unzip tutorial_module.zip

To run the example script:

3. Navigate into tutorial_module

4. Create build directory

5. Navigate into build

6. Run ‘cmake ..’

cd tutorial_module
mdkir build
cd build 
cmake ..

7. This generates a Makefile, which you can then run with ‘make’:

make

8. You now have a custom module library: “libdspc_tutorial.a”

Integrating your new module into the AWECoreOS sample applications

This section assumes:

• you already have an AWECoreOS package installed on your Linux-based target.

• you can modify/rebuild the provided example apps.

Add your module definitions to ModuleList.h

1. Navigate into the AWECoreOS/Include directory and open the ModuleList.h file.

2. Add the symbol variables:

3. add the new module variables to the LISTOFCLASSOBJECTS array CUSTOM_LIST entry:

4. In this case, we are making a new array ‘CUSTOM_LIST’, which contains our new module symbols and then we add ‘CUSTOM_LIST’ to ‘LISTOFCLASSOBJECTS’:

Now that we have added the symbols, we can close ModuleLists.h and move on to the linker step. Read the next section to understand more of the details behind what you just did.

Understanding how it works

ModuleList.h contains an array LISTOFCLASSOBJECTS that represents the list of all modules to be linked in.

Notice in the Example Apps (HelloWorld.c), that the initialization API function aweOS_init() takes an argument for ‘module_descriptor_table’, which is assigned to the ‘LISTOFCLASSOBJECTS’:

This is how AWECoreOS knows which modules to link into the app.

To use your new custom modules, you must add their symbols to this array.

Look at the details of ModuleList.h. Notice that we first declare the module symbols as extern const int variables:

And then they are added to a preprocessor array:

The master LISTOFCLASSOBJECTS is built up from smaller lists as shown to allow more straightforward module management.

Also notice the naming convention. All module symbols are prefaced with ‘awe_mod’, and end with “Class”. This naming convention must be followed to successfully link the new module classes.

Linking the Module Lib

Obviously, the new custom module C library must be linked into the AWECoreOS application, or else the symbols won’t be found.

• Open each of the AWECoreOS example’s ‘CMakeLists.txt’ file and add the full path to libdspc_tutorial.a to the linking step in the cmake script:

Because all of the examples share the same ModuleList.h file, each example’s CMakeLists.txt must be updated.

• Now rebuild the apps, and you’re done:

• cd into the Bin folder.

• Run one of the Sample Apps, to activate AWECoreOS.

Here we are running “HelloWorld”.

Under ‘Target > List Modules’ in AWE Server, you should see the new Custom Tutorial Modules in the list:

Analysis of CMakeLists.txt file

Generally speaking, in order to customize this procedure to use your own modules, you will only need to change:

• The project name

• The list of source files

Details

• Set minimum version

• Define the project name

Define the include directories

• Top level include directory contains the custom module header files and other required AWE functions and types.

• The include/Targets directory contains target specific type definitions.

• Both must be included.

• Add the list of custom module C files to your CMakeLists.txt source_files section.

Helpful Linux Commands: