iadk: Add module pass buffer definition

Add a definition specifying the size of space reserved in module memory for
module handle and a iadk adapter.

Add a brief description of the iadk module loading sequence.

Signed-off-by: Adrian Warecki <adrian.warecki@intel.com>

Author: softwarecki

src/include/sof/audio/module_adapter/iadk/api_version.h

@@ -19,4 +19,10 @@
 #define IADK_MODULE_API_CURRENT_VERSION	MODULE_API_VERSION_ENCODE(IADK_MODULE_API_MAJOR_VERSION, \
 	IADK_MODULE_API_MIDDLE_VERSION, IADK_MODULE_API_MINOR_VERSION)
 
+/* Defines the size of the space reserved within ModuleHandle for SOF to store its private data.
+ * This size comes from the IADK header files and must match the IADK API version.
+ * Please do not modify this value!
+ */
+#define IADK_MODULE_PASS_BUFFER_SIZE		320
+
 #endif /* __MODULE_ADAPTER_IADK_API_VERSION_H__ */

src/include/sof/audio/module_adapter/iadk/iadk_module_adapter.h

@@ -15,6 +15,8 @@
 #include <module_initial_settings.h>
 #include <adsp_stddef.h>
 #include <system_error.h>
+#include <sof/common.h>
+#include <api_version.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -112,6 +114,8 @@ namespace dsp_fw
 		intel_adsp::ProcessingModuleInterface &processing_module_;
 	};
 
+STATIC_ASSERT(sizeof(IadkModuleAdapter) <= IADK_MODULE_PASS_BUFFER_SIZE, IadkModuleAdapter_too_big);
+
 } /* namespace dsp_fw */
 
 } /* extern "C" */

src/include/sof/audio/module_adapter/iadk/system_agent.h

@@ -72,6 +72,41 @@ namespace system
 #ifdef __cplusplus
 extern "C" {
 #endif
+/*
+ * The process of loading a IADK module is quite complicated. The function call stack is as follows:
+ *
+ *   1. IADK module adapter initialization function (modules_init) pass module entry point to the
+ *	system_agent_start function.
+ *
+ *   2. system_agent_start: This function creates an instance of the SystemAgent class on the stack
+ *	and then calls the module entry point function (ModuleEntryPoint) passing a pointer to the
+ *	SystemAgent object as a parameter.
+ *
+ *   3. ModuleEntryPoint(system_agent): Creates a ModuleFactory object of the module on the stack
+ *	(inheriting from ProcessingModuleFactoryInterface) and then calls the
+ *	LoadableModuleMain(system_agent, module_factory, placeholder) function, which is the default
+ *	entry point for all IADK modules. Placeholder is part of the .bss section intended for
+ *	a given module instance, with its address is determined based on the instance ID.
+ *
+ *   4. LoadableModuleMain(system_agent, module_factory, placeholder): Calls the CheckIn method
+ *	(variant with 7 parameters) of the SystemAgent class.
+ *
+ *   5. SystemAgent.CheckIn(7): Calls the Create method from the ModuleFactory object.
+ *
+ *   6. ModuleFactory.Create(system_agent, placeholder): Creates an instance of the module class
+ *	(inheriting from ProcessingModule) at the address pointed to by placeholder.
+ *	The ProcessingModule class contains a module_handle field, which reserves an area in memory
+ *	of size IADK_MODULE_PASS_BUFFER_SIZE bytes. The constructor of this class calls the CheckIn
+ *	method (the variant with 3 parameters) from the SystemAgent class, passing a pointer to self
+ *	and a pointer to module_handle.
+ *
+ *   7. SystemAgent.CheckIn(3): Stores the address of module_handle in a private variable and
+ *	creates an instance of the IadkModuleAdapter class in this location.
+ *
+ * The saved address of the module_handle (the adapter's IADK instance) is returned in the CheckIn
+ * method (the variant with 7 parameters) via a parameter that initially contained the address to
+ * the agent system. The system_agent_start function returns it in the variable adapter.
+ */
 void *system_agent_start(uint32_t entry_point, uint32_t module_id, uint32_t instance_id,
 			 uint32_t core_id, uint32_t log_handle, void *mod_cfg);
 #ifdef __cplusplus