PowerAQ Customized Module Porting Guide

1 Build the customized module into the system

1.1. Prepare files

Create a folder named swip in path /src/multimedia/audio-misc/ppc/model and copy swip_common from /src/multimedia/audio-misc/ppc/model/SWIP_example to this folder.

Then create a folder named $(MODULE). In this document, we name the customized module to MyPP as an example.

Fig.1 create a folder named MyPP

Copy the source codes of the customized module to this folder and then create three new files, $(MODULE)_api.c, $(MODULE)_api.h and $(MODULE)_type.c.

Fig.2 porting all the customized PP source codes to this folder

Fig. 3 create three files in this folder

1.2. Declare the module handler

In $(MODULE)_type.h, a handler is declared. This handler is required by the post processing model when the module functions are called.

Fig. 4 the SWIP handler

In the module handler, there are three mandatory members, in_ch, out_ch and mem_hdl. The in_ch and out_ch indicate the input and output channel numbers. They will be set and queried by PowerAQ model during the processing procedure. The mem_hdl is defined in mem.h. It can help each post-processing module to monitor the resource allocated by PowerAQ model. Parameters in the customized module, which can be tuned by tool, are also included in this handler.

1.3. The API header

In $(MODULE)_api.h, the developers need to define the type ID firstly as an identification for the customized post processing module. The type ID should be unique and range from 0x80 to 0xFF. Then declare an function named $(MODULE)_get_handler() so the PowerAQ model could obtain the module handler by calling it

Fig. 5 type ID and the declaration of $(SWIP)_get_handler()

1.4. The wrapper functions

$(MODULE)_get_handler() is implemented in $(MODULE)_api.c.

Fig. 6 the implementation of $(SWIP)_get_handler()

As shown in /src/multimedia/audio-misc/ppc/model/inc/swip_type.h, there are 8 function pointers defined in struct SWIP_HANDLER. All the wrappers need to be implemented in $(MODULE)_api.c and then assigned to each function pointer in the swip handler when $(MODULE)_get_handler() is called. In the next few sections, these functions will be introduced briefly.

1.4.1 $(MODULE)_get_mem_size

$(MODULE)_get_mem_size() returns the total memory size needed by the customized module and PowerAQ model will allocate memory for it according to the return value.

Fig. 7 the sample implementation of $(MODULE)_get_mem_size()

1.4.2 $(MODULE)_init

After allocating memory for a specific module, PowerAQ model will call $(MODULE)_init(). In this function, the starting address should be assigned to each pointer in $(MODULE)_HANDLER using the memory allocated by PowerAQ model. The address of this memory is passed from PowerAQ model via the pointer void* pp_hdl. The API which initializes the customized module should be called in this function as well.

Fig. 8 the sample implementation of $(MODULE)_init()

1.4.3 $(MODULE)_set_channel

$(MODULE)_set_channel() will be called by PowerAQ model to inform the customized module about the channel number of the input data. Normally PowerAQ model does not know the output channel number (*out_channel will be 0), so the customized module need to fill the value of hdl->out_ch. If the post processing library has an API to set the channel number, call it in this function.

Fig. 8 the sample implementation of $(MODULE)_set_channel()

1.4.4 $(MODULE)_set_para and $(MODULE)_get_para

$(MODULE)_set_para() and $(MODULE)_get_para() are called by PowerAQ model to modify or obtain the value of the parameters in this module. APIs from the customized post processing library could be called in these functions. Please note that the ID for each parameter should be defined beforehand in /src/multimedia/audio-misc/ppc/model/inc/id.h.

Fig. 9 parameter IDs for the customized module are defined in id.h


Fig. 10 the sample implementation of $(MODULE)_set_para()

Fig. 11 the sample implementation of $(MODULE)_get_para()

1.4.5 $(MODULE)_dump_para

$(MODULE)_dump_para() is called by PowerAQ model to dump all the current parameter setting.

Fig. 12 the sample implementation of $(MODULE)_dump_para()

1.4.6 $(MODULE)_process

$(MODULE)_process() is called to apply the post processing effect to audio data. The processing API from the customized library should be called in this function. Please note that the data sent and received by PowerAQ model is not interleaved but stored in separate buffers according to different channels. If the customized post processing library needs interleaved data, they should be prepared in this function as well.

Fig. 12 the sample implementation of $(MODULE)_process()

1.4.7 $(MODULE)_reset

If the customized module has buffers containing history data, which will be used as reference when doing post processing, it will need to be reset when the bypass state of the module is changed. In this case, $(MODULE)_reset() will be called by PowerAQ model and the history data should be reset in this function.

Fig. 14 the sample implementation of $(MODULE)_reset()

1.5. Build the library

After all the source files are finished editing, create Makefile and  License in folder $(MODULE). Then add a bb script in /meta/meta-mediatek-aud/recipes-multimedia/aud-misc. After that, partial build the library with the command below:

“bitbake mypp –c compile –f”

If build passed, copy the output library in folder /build/tmp/work/aarch64-poky-linux/$(MODULE)/1.0-r0/$(MODULE)-1.0/ to /src/multimedia/audio-misc/ppc/model/libs

1.6. Add the library to PowerAQ model

Copy $(MODULE)_api.h to /src/multimedia/audio-misc/ppc/model/inc.

In /src/multimedia/audio-misc/ppc/model/src/ppc_swip.h, increase the SWIP_NUM by 1.

Fig. 15 increase the SWIP_NUM in ppc_swip.h

In /src/multimedia/audio-misc/ppc/model/src/ppc_swip.c, include the header file “$(MODULE)_api.h” and add the customized SWIP to swip_map in function swip_map_init().

Fig. 16 include $(MODULE)_api.h

Fig. 17 add customized module to swip map

Edit the Makefile in /src/multimedia/audio-misc/ppc, add the customized lib to it.

Fig. 18 edit Makefile

Rebuild the load, now the customized module has been added to the system successfully!

2. Add customized module in PowerAQ

2.1. Create a new project

Click button File -> New Project, a window like Fig. 20 would appear.

                                                                  Fig. 19 create a new project

Fill in the Project Name and Project Path, and then click OK.

                                                                        Fig. 19 create a new project

Now the new project has been created, the tool interface will appear as Fig. 21. 

                                                   Fig. 20 the tool interface after create new project

2.2. Add customized element to PowerAQ

                                                                  Fig. 21 add new element type

As it is showed in Fig. 21, click Tools -> New Element Type to add new customized element type to PowerAQ. Then a window like Fig 22 would pop up. In page Element Type, the element informations should be filled. Please remember that the Type Id should be identical to what have been set in $(MODULE)_api.h

                                                                         Fig. 22 edit element info

Then turn to page Parameter like in Fig. 23, enter the Parameter Num and the information of each parameter. Remember that the name of each parameter should match those previously defined in /src/multimedia/audio-misc/ppc/model/inc/id.h. The Integer Value means the default setting of each parameter.

                 Fig. 23 the newly added element

2.3. Create a signal flow which includes the customized module

Now the customized module can be added to the post processing signal flow. The element setting can be tuned by double clicking on it and then modifying the values of each parameter.


                                                                       Fig. 24 tuning the element

Click File -> Gen Config File, there will be 2 files generated in the selected folder as in Fig 26.

                                  Fig. 25 generate the cfg files

                                          Fig. 26 cfg files

Copy those config files in a USB flash drive and insert it to the platform. Then connect the test platform to the PowerAQ tool. After clicking Tools -> Update config file as in Fig. 27, the signal flow running on the platform will be the one showed in the tool interface and the parameters can be tuned dynamically now.

                                                             Fig. 27 update the config file path

When the signal flow is finished editing, click File -> Gen Header File, and there would be 5 files generated in the selected folder.

                                                                        Fig. 28 the post processing chain

                                       Fig. 29 the generated files

Copy those files to /src/multimedia/audio-misc/ppc/model/inc/ and rebuild the load, and the custom-designed post processing chain can be running on the system now.