{"id":40627189,"url":"https://github.com/thesofproject/converged-sof-modules","last_synced_at":"2026-01-21T07:25:52.963Z","repository":{"id":48991222,"uuid":"371484502","full_name":"thesofproject/converged-sof-modules","owner":"thesofproject","description":"Staging repo with Converged SOF module examples and integration tools","archived":false,"fork":false,"pushed_at":"2025-01-31T09:29:32.000Z","size":3892,"stargazers_count":2,"open_issues_count":1,"forks_count":2,"subscribers_count":45,"default_branch":"main","last_synced_at":"2025-01-31T10:29:12.031Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thesofproject.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-27T19:35:22.000Z","updated_at":"2025-01-31T09:29:36.000Z","dependencies_parsed_at":"2025-01-31T10:24:34.786Z","dependency_job_id":"5833e63b-2988-4403-8b73-84afd353285a","html_url":"https://github.com/thesofproject/converged-sof-modules","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/thesofproject/converged-sof-modules","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesofproject%2Fconverged-sof-modules","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesofproject%2Fconverged-sof-modules/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesofproject%2Fconverged-sof-modules/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesofproject%2Fconverged-sof-modules/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thesofproject","download_url":"https://codeload.github.com/thesofproject/converged-sof-modules/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thesofproject%2Fconverged-sof-modules/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28629915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-21T07:25:52.890Z","updated_at":"2026-01-21T07:25:52.944Z","avatar_url":"https://github.com/thesofproject.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Converged Sound Open FW - modules development\r\n\r\nThis repository contains three converged sound open firmware module examples\r\nsuch as: aca_module, amplifier_module and downmixer_module and whole building\r\ninfrastructure (i.e. makefiles, source files and API headers) required to\r\nbuild module examples and loadable libraries. Loadable library is composed by\r\na set of N precompiled loadable modules.\r\n## Modules\r\n\r\nModule implementation examples are provided in ``\u003crepo_dir\u003e/modules/``\r\ndirectory.\r\n\r\n### Module API\r\nModule requirements:\r\n- implements the *ProcessingModuleInterface* class;\r\n- implements the *ProcessingModuleFactoryInterface* class;\r\n- declares itself as \"loadable\" with help of the macro *DECLARE_LOADABLE_MODULE*.\r\n\r\nThe *ProcessingModuleInterface* defines methods that firmware will call to\r\nconfigure and to start the stream processing. The *ProcessingModuleInterface*\r\nheader is available at:\r\n``\u003crepo_dir\u003e/FW/src/intel_adsp/include/processing_module_interface.h``\r\nThere is also *ProcessingModule* class, which provided is as a partial default\r\nimplementation of the *ProcessingModuleInterface* class:\r\n``\u003crepo_dir\u003e/FW/src/intel_adsp/include/processing_module.h``\r\n\r\n#### ProcessingModule class\r\nA custom module class needs to implement at least these three functions:\r\n- **ProcessingModule::Process()**\r\nProcesses the stream buffers extracted from the input pins and produces the\r\nresulting signal in the stream buffer of the output pins.\r\n\r\n- **ProcessingModule::SetConfiguration()**\r\nApplies the upcoming configuration message for the given configuration ID.\r\n\r\n- **ProcessingModule::SetProcessingMode()**\r\nSets the processing mode for the module.\r\n\r\nOptionally, the following methods can be overridden in *ProcessingModule*:\r\n- **ProcessingModule::GetConfiguration()**\r\nRetrieves the configuration message for the given configuration ID. \r\n \r\n- **ProcessingModule::Reset()**\r\nUpon a call to this method, the firmware requires the module to reset its\r\ninternal state into a well-known initial value. Parameters that may have been\r\nset through SetConfiguration() are expected to be left unchanged. \r\n\r\n#### ProcessingModuleFactory class\r\nThe *ProcessingModuleFactoryInterface* class handles the creation of the custom\r\nprocessing module components. Following methods should be implemented:\r\n- **ProcessingModuleFactory::Create()**\r\nCreates a RegisteredProcessingModule instance. The custom implementation of the\r\nCreate method is expected to handle the initialization of the custom module\r\ninstances. \r\n\r\n- **ProcessingModuleFactory::GetPrerequisites()**\r\nIndicates the prerequisites for module instance creation. Firmware calls this\r\nmethod before each module instance creation.\r\n\r\n### Modules Configuration\r\nThe module design configuration is placed in binamp file. The module examples\r\nbinmaps are placed in:\r\n``\u003crepo_dir\u003e/FW/intel_common/module_binmaps``\r\nModule binmaps contains information about several module parameters e.g. module\r\nuuid, module version, input/output pins, number of channels, sample size,\r\nschedule capabilities. Ultimately, binmaps should be customized according to\r\nuser needs.\r\n\r\n#### Module name\r\nUsage:\r\n```\r\nmodule module_type module_name\r\n```\r\nExample:\r\n```\r\nmodule o AMPLI\r\n```\r\n*module_type* can take following values:\r\n- *o*   - optional module\r\n- *b*   - built-in module\r\n- *ba*  - built-in auto-init module\r\n- *d*   - module packaged into separate file\r\n- *da*  - auto-init module packaged into seperate file\r\n- *l*   - internal common sections module\r\n\r\n*module_name* is a string name o module. It does not have to be unique. Should\r\nnot exceed 8 characters.\r\n\r\n#### Module UUID\r\nUsage:\r\n```\r\nuuid uuid_number\r\n```\r\nExample:\r\n```\r\nuuid 8075F4F8-6214-4A61-8C08-884BE5D14FF8\r\n```\r\n*uuid_number* unique UUID number. See [UUID Wikipedia](https://en.wikipedia.org/wiki/Universally_unique_identifier)\r\nfor a description.\r\n\r\n#### Module pretty name\r\nUsage:\r\n```\r\nname pretty_name\r\n```\r\nExample:\r\n```\r\nname Aca module example\r\n```\r\n*pretty_name* does not have to be unique. It is not limited to 8 characters.\r\n#### Module version\r\nUsage:\r\n```\r\nversion_major major_value\r\nversion_minor minor_value\r\nversion_hotfix hotfix_value\r\nversion_build build_value\r\n```\r\nExample: \r\n```\r\nversion_major 0x1\r\nversion_minor 0x0\r\nversion_hotfix 0x0\r\nversion_build 0x0\r\n```\r\n- *version_major* - shall be used only for vendor parameter structure change\r\n(user decide how to use version parameter);\r\n- *version_minor* - shall be used only for internal changes (optimizations,\r\nbug fix);\r\n- *version_hotfix* - shall be used during the bug fixing period;\r\n- *version_build* - shall be incremented with new build.\r\n\r\n#### Module affinity\r\nUsage:\r\n```\r\naffinity_mask mask\r\n```\r\nExample:\r\n```\r\naffinity_mask MASTER_CORE_AFFINITY\r\n```\r\n*mask* is a bit-mask of cores allowed to execute module. Macros reffering this\r\nmask are defined at:\r\n``\u003crepo_dir\u003e/FW/portable/include/modules.h``\r\n\r\n#### Module instance count\r\nUsage:\r\n```\r\ninstance_count count\r\n```\r\nExample:\r\n```\r\ninstance_count +1\r\n```\r\n*instance_count* refers to number of module instance. The value should be\r\nprovided with \"+\" at beginning. It will be added to basic instance count.\r\n\r\n#### Scheduler domain type:\r\nUsage: \r\n```\r\ndomain_types type\r\n```\r\nExample\r\n```\r\ndomain_types DP\r\n```\r\nFollowing domain types are available :\r\n- *LL* - low latency domain is intended to be able transfer data through DSP\r\nsubsystem within 2ms. Processing modules used in that domain must be able to\r\nwork on limited number of samples. To meet 2ms pipeline latency on stream\r\nsampled at 48 kHz stream needs to be processed in 1ms periods i.e. using maximum\r\n48 sample blocks. \r\n- *DP* - Data processing domain is intended host all processing that does not\r\nfit in definition of low latency domain. It is important that this domain is\r\nstill real time and latency sensitive.\r\n\r\n#### Module type\r\nUsage:\r\n```\r\ntype class_name\r\n```\r\nExample:\r\n```\r\ntype AudClassModule\r\n```\r\n*class_name* refers to module class type supported by firmware. Available\r\nmodules classes are placed in:\r\n``\u003crepo_dir\u003e/FW/intel_common/module_binmaps/dsp_fw_common.binmap``\r\nin ``# type \u003cmod_func_type\u003e`` section.\r\n\r\n#### Module stack size\r\nUsage:\r\n```\r\nstack_size size\r\n```\r\nExample:\r\n```\r\nstack_size 1000\r\n```\r\n*stack_size is size of stack that module instance requires for its task.\r\nIt refer only to DP scheduler domain.\r\n\r\n\r\n#### Scheduling capabilities\r\nUsage:\r\n```\r\nsched_caps scheduling_period multiples_supported\r\n```\r\nExample:\r\n```\r\nsched_caps 1 all\r\n```\r\n- *scheduling_period* - scheduling period should be given in samples per channel\r\n(i.e. 1 sample = 1 sample per channel) as a hexadecimal value.\r\n- *multiples_supported* - indicates the supported period multiples. Available\r\nvalues are placed in:\r\n``\u003crepo_dir\u003e/FW/intel_common/module_binmaps/dsp_fw_common.binmap``\r\nin ``# multiples_supported \u003clist_of_supported_multiples\u003e`` section.\r\n\r\n#### Module config\r\nUsage:\r\n```\r\nmod_cfg PAR_0 PAR_1 PAR_2 PAR_3 IS_BYTES CPS IBS OBS MOD_FLAGS CPC OBLS\r\n```\r\nExample:\r\n```\r\nmod_cfg 0 0 0 0 4096 500000 180 180 0 5000 0\r\n```\r\n*mod_cfg* required following parameters:\r\n- *PAR0-3* - any module parameters;\r\n- *IS_BYTES* - actual size of instance .bss (pages);\r\n- *CPS (Cycles Per Second)* - indicates the max count of cycles per second which\r\nare granted to a certain module to complete the processing of its input and\r\noutput buffers;\r\n- *IBS (Input Buffer Size)* - input buffer size (in bytes) that module shall\r\nprocess (within ProcessingModuleInterface::Process()) from every connected\r\ninput pin;\r\n- *OBS (Output Buffer Size)* - output buffer size (in bytes) that module shall\r\nproduce (within ProcessingModuleInterface::Process()) on every connected\r\noutput pin;\r\n- *MOD_FLAGS (Module Flags)* - for future use\r\n- *CPC (Cycles Per Chunk)* - indicates the max count of Cycles Per Chunk which\r\nare granted to a certain module to complete the processing of its input and\r\noutput buffers;\r\n- *OBLS (Output Block Size)* - for future use.\r\n\r\n#### Input/Output pins\r\nUsage:\r\n```\r\npin in\r\nstream_type type\r\nsample_rates rates\r\nsample_sizes sizes\r\nsample_containers containers\r\nchannel_cfg ch_cfg\r\n```\r\nExample:\r\n```\r\npin in\r\nstream_type pcm\r\nsample_rates 44.1k 48k\r\nsample_sizes sample_16b sample_24b sample_32b\r\nsample_containers container_16b container_32b\r\nchannel_cfg ch_mono ch_stereo\r\n```\r\n\r\nA pin is a connector that transmits PCM audio streaming: one pin can transmit\r\nseveral channels (for example, a stereo signal requires only one pin). There are\r\ntwo pin types: input (*in*) and output (*out*). Additional pin properties are:\r\n- *stream_type*\r\n- *sample_rates*\r\n- *sample_sizes*\r\n- *sample_containers*\r\n- *channel_cfg*\r\n\r\nValues for above properties are available in common binmap file:\r\n``\u003crepo_dir\u003e/FW/intel_common/module_binmaps/dsp_fw_common.binmap``\r\nin respectively: \r\n- ``# stream_type \u003ctype\u003e``,\r\n- ``# sample_rates \u003clist_of_supported_sample_rates\u003e``,\r\n- ``# sample_sizes \u003clist_of_supported_sample_sizes\u003e``,\r\n- ``# sample_containers \u003clist_of_supported_sample_containers\u003e``,\r\n- ``# channel_cfg \u003clist_of_supported_channel_configurations\u003e``\r\nsections.\r\n \r\n### Modules Examples\r\n#### Aca_module\r\nAca_module  is an implementation example of post-processing module which simply\r\namplifies the input stream by a constant gain value. The aca_module is a single\r\ninput-single output module.\r\n#### Amplifier_module\r\n\r\nAmplifier_module is a post-processing module (it should be used on the render\r\npath). This is a very basic module implementation supporting one pin in input\r\nand one pin in output. The module implementation doesn't include any compiled\r\nlibrary. The parameters set (four parameters) is defined on one configuration\r\nID. \"target_gain\" is the gain value that is applied in the module. If\r\n\"target_gain\" exceeds the range defined with \"min_gain\" and \"max_gain\", the\r\napplied value is replaced with the max/min limit. \"smoothing_factor\" parameter\r\nis the convergence speed ramp to reach the new gain value.\r\n\r\n#### Downmixer_module\r\n\r\nDownmixer_module is a pre-processing module (it should be used on the capture\r\npath). This is a more advanced module implementation as it supports two pins in\r\nthe input. The second input pin is used for the reference signal: when\r\nperforming a playback and a record at the same time, the playback signal is sent\r\non the second input pin as a reference, as needed for an echo canceller for\r\nexample. As for the amplifier, the parameters set is basic and defined on one\r\nconfiguration ID. The output is the result of a mix between input and reference\r\nsignal balanced with \"main_div\" and \"ref_div\" parameter values:\r\n``output_signal = input_signal/main_div + reference_signal/ref_div``\r\n\r\n### Building toolchain from source\r\n\r\nBuild the xtensa cross-compilation toolchains with crosstoolg-ng for lx7hifi4\r\nplatform. Building instruction is available here: [build toolchains](https://thesofproject.github.io/latest/getting_started/build-guide/build-from-scratch.html#step-2-build-toolchains-from-source).\r\n\r\nNOTE: Switch to branch https://github.com/thesofproject/crosstool-ng/tree/sof-gcc10x\r\nfor crosstool-ng and https://github.com/thesofproject/xtensa-overlay/tree/sof-gcc10.2\r\nfor xtensa-overlay repositories.\r\n\r\n### Building modules\r\n\r\nModule examples (aca_module, amplifier_module and downmixer_module) are placed\r\nin ``\u003crepo_dir\u003e/modules/``. In order to build the example, enter the module\r\nbuild directory ``\u003crepo_dir\u003e/modules/\u003cmodule_example_name\u003e/build``\r\n(e.g. ``\u003crepo_dir\u003e/modules/aca_module/build``) and invoke make command i.e.:\r\n```\r\nmake \u003cplatform_name\u003e \u003cconfig\u003e TOOLSCHAIN=\u003ctoolchain_name\u003e OVERLAY_TOOLS_DIR=\u003coverlay_dir\u003e XTENSA_TOOLS_DIR=\u003cxtensa_tools_dir\u003e\r\n\r\n\u003cplatform_name\u003e     refers to platform target e.g. lx7hifi4_plat / lx7hifi4-s_plat\r\n\u003cconfig\u003e            release/debug config\r\n\u003ctoolchain_name\u003e    toolchain name\r\n\u003coverlay_dir\u003e       path to toolchain bin directory of toolchain generated by crosstool-ng\r\n\u003cxtensa_tools_dir\u003e  path to xtensa tools directory\r\n```\r\n\r\nExamples:\r\n- build module using xtensa-lx7hifi4-elf toolchain (OVERLAT_TOOLS_DIR should point\r\nto the toolchain bin directory)\r\n```\r\nmake lx7hifi4_plat release TOOLSCHAIN=\"xtensa-lx7hifi4-elf\" OVERLAY_TOOLS_DIR=\"~/lx7hifi4_xtensa_overlays/crosstool-ng/builds/xtensa-lx7hifi4-elf/bin/\"\r\n```\r\n- build module using xtensa toolchain\r\n```\r\nmake lx7hifi4_plat release TOOLSCHAIN=\"xtensa\" XTENSA_TOOLS_DIR=\"C:\\usr\\xtensa\\Xplorer-8.0.11-workspaces\\install\\tools\"\r\n```\r\n\r\nBuilding artifacts will be placed in following directory:\r\n``\u003crepo_dir\u003e/modules/\u003cmodule_example_name\u003e/build/out``\r\n\r\nNOTE: At the moment building is available only for lx7hifi4_plat and lx7hifi4-s_plat \r\nplatforms with \"xtensa-lx7hifi4-elf\" toolchain.\r\n## Loadable library\r\n\r\nLoadable library contains set of N precompiled loadable modules. In order\r\nto build loadable library, firstly the specific module/modules should be\r\ncompiled (see [Building modules](#building-modules) section).\r\n\r\n### Build_library.py script\r\nIn order to build loadable library the:\r\n``\u003crepo_dir\u003e/scripts/build_library.py``\r\ncan be utilized. \r\n\r\n```\r\npython3 build_library.py --help\r\nusage: build_library.py [-h] [-o OUTPUT_PATH] [-c {release,debug}] [-a ATTR_FILE_PATH] [-t {xtensa,xtensa-lx7hifi4-elf}] platform_name library_name library_version modules_list\r\n\r\npositional arguments:\r\n  platform_name         name of target platform\r\n  library_name          name of output library\r\n  library_version       version of output library\r\n  modules_list          modules to be included in output library (e.g. \"module_1_name, module_2_name\")\r\n\r\noptional arguments:\r\n  -h, --help            show this help message and exit\r\n  -o OUTPUT_PATH, --output_path OUTPUT_PATH\r\n                        path to output build folder (default: ./out)\r\n  -c {release,debug}, --config {release,debug}\r\n                        type of config (default: release)\r\n  -a ATTR_FILE_PATH, --attr_file_path ATTR_FILE_PATH\r\n                        path to xml attribute file (default: /mnt/c/conv-fdk/artifacts/dsp_fw_example_release.xml)\r\n  -t {xtensa,xtensa-lx7hifi4-elf}, --toolschain {xtensa,xtensa-lx7hifi4-elf}\r\n                        default: xtensa-lx7hifi4-elf\r\n```\r\nBefore invoking ``build_library.py`` proper tools (e.g. meu tool, signing keys)\r\npaths should be set in: ``\u003crepo_dir\u003e/scripts/lib_config.conf``\r\n\r\n``build_library.py`` script builds loadable library containig modules\r\npassed in ``modules_list`` argument. It searches modules binaries\r\n(``\u003cmodule_name\u003e.dlm.a files``) in default modules build location i.e.:\r\n``\u003crepo_dir\u003e/modules/\u003cmodule_name\u003e/build/out/lx7hifi4_plat/\u003cconfig\u003e/``\r\nAbove script also calculates the loadable library address using firmware memory\r\nfootprint files (memory footprint file example is available:\r\n``\u003crepo_dir\u003e/artifacts/dsp_fw_example_release.xml`` and it is used by script by\r\ndefault - it can be changed by ``-a`` flag). Ultimately, memory footprint file\r\nwill be shared as a part of a release package.\r\n\r\n### Usage examples\r\n\r\nBuilds library called \"aca_lib\" containing \"aca_module\" for lx7hifi4_plat platform.\r\nThe library version is set to 1.8. Script uses release aca_module binary as\r\ndefault. Build artifacts will be placed in out folder by default.\r\n```\r\npython3 build_library.py lx7hifi4_platorlake aca_lib 1.8 aca_module\r\n```\r\n\r\nBuilds library called \"example_lib\" containing \"aca_module\" and\r\n\"amplifier_module\" for lx7hifi4_plat platform. The library version is set to 1.8.\r\nScript uses release aca_module binary as default. Build artifacts will be placed\r\nin out folder by default.\r\n```\r\npython3 build_library.py lx7hifi4_plat example_lib 1.8 \"aca_module amplifier_module\"\r\n```\r\n\r\n## Getting started\r\n\r\n1. Build the xtensa cross-compilation toolchains ([Building toolchain](building_toolchain_from_source) section).\r\n2. Configure module - use default or modify binmap file for specific module ([Module configuration](modules_configuration) section).\r\n3. Build module/modules ([Building modules](building_modules) section).\r\n4. Build loadable library containig specific module/modules ([Loadable library](loadable_library) section).\r\n\r\n## Repository content - summary\r\n\r\n- ``\u003crepo_dir\u003e/linux/sw/adsp_fw_builder`` - adsp_fw_builder for linux.\r\nadsp_fw_builder is a DSP firmware image creation tool used to create manifest.\r\n\r\n- ``\u003crepo_dir\u003e/windows/sw/adsp_fw_builder`` - adsp_fw_builder for windows.\r\n\r\n- ``\u003crepo_dir\u003e/modules/`` - directory containing module examples\r\n\r\n- ``\u003crepo_dir\u003e/scripts/build_library.py`` - script for building loadable\r\nlibrary (see [Loadable library](#loadable-library) section)\r\n\r\n- ``\u003crepo_dir\u003e/FW/src/intel_adsp/`` - directory containing building\r\ninfrastracture e.g. necessary source files, headers and makefiles. \r\n\r\n- ``\u003crepo_dir\u003e/FW/intel_common/module_binmaps`` - directory containig\r\nmodules and firmware binmaps i.e. files used for configuration (e.g. setting\r\ninput/output pins, supported sample rate etc.).\r\n\r\n- ``\u003crepo_dir\u003e/artifacts/dsp_fw_example_release.xml`` - example of dsp memory\r\nfootprint file used in building process to calculate loadable library address\r\n\r\n- ``\u003crepo_dir\u003e/docs/INTEL_ADSP_Module_API.chm`` - module API documentation","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesofproject%2Fconverged-sof-modules","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthesofproject%2Fconverged-sof-modules","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthesofproject%2Fconverged-sof-modules/lists"}