module_adapter: add README for library and iadk subsystems

Adds documentation detailing the ZEPHYR user space and Intel ADSP third
party integration mechanisms via the Module Adapter architecture.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>

Author: lrgirdwo

src/audio/module_adapter/iadk/README.md

@@ -0,0 +1,85 @@
+# Intel Audio Development Kit (`module_adapter/iadk`)
+
+The `iadk` directory provides the Module Adapter implementation for external 3rd-party audio algorithms developed using the **Intel Audio Development Kit (IADK)**.
+
+Unlike the native SOF `module_interface` API (written primarily in C), the IADK modules are object-oriented C++ classes that derive from `intel_adsp::ProcessingModuleInterface`. The SOF `IadkModuleAdapter` acts as a C++ to C "glue layer" that wraps these IADK methods so they can be natively plugged into the SOF `module_adapter` pipeline without modification to the module's pre-compiled binary.
+
+## Architecture and Class Hierarchy
+
+The system defines an `IadkModuleAdapter` class which internally holds an instance of the 3rd-party `ProcessingModuleInterface`.
+
+```mermaid
+classDiagram
+    class SOF_ModuleAdapter {
+        +init
+        +process
+        +bind
+    }
+
+    class iadk_wrapper {
+        iadk_wrapper_process
+        iadk_wrapper_init
+    }
+
+    class IadkModuleAdapter {
+        -processing_module_
+        +IadkModuleAdapter_Init
+        +IadkModuleAdapter_Process
+        +IadkModuleAdapter_SetConfiguration
+    }
+
+    class ProcessingModuleInterface {
+        +Init
+        +Process
+        +SetConfiguration
+        +Reset
+    }
+
+    class IADK_3rdParty_Algorithm {
+        +Init
+        +Process
+    }
+
+    SOF_ModuleAdapter --> iadk_wrapper : C Function Pointers
+    iadk_wrapper --> IadkModuleAdapter : Instantiates and Wraps
+    IadkModuleAdapter --> ProcessingModuleInterface : Polymorphic Interface
+    ProcessingModuleInterface <|-- IADK_3rdParty_Algorithm : Inherits
+```
+
+## System Agent and Instantiation Flow
+
+Because the actual module resides in an external binary, it requires a "System Agent" to correctly instantiate the C++ objects during the component's `init` phase.
+
+1. The OS host driver sends an IPC `INIT_INSTANCE` command for the module.
+2. The `system_agent_start()` function intercepts this, invokes the dynamic module's `create_instance` entry point (which invokes a `ModuleFactory`).
+3. The `SystemAgent` deduces the pin count (interfaces) and initial pipeline configurations using `ModuleInitialSettingsConcrete`.
+4. The factory allocates the concrete algorithm and checks it back into SOF through `SystemAgent::CheckIn`.
+
+```mermaid
+sequenceDiagram
+    participant IPC
+    participant SA
+    participant Fac
+    participant Mod
+
+    IPC->>SA: Trigger Mod Creation
+    SA->>Fac: CI invokes create_instance
+    Fac->>Fac: Deduce BaseModuleCfgExt
+    Fac->>Mod: operator new instantiate
+
+    Fac->>SA: SystemAgent CheckIn Module
+    SA->>Adp: Create new IadkModuleAdapter Module
+
+    SA-->>IPC: Return CPP adapter to C Pipeline
+```
+
+## Data Buffer Translation
+
+A significant task of `IadkModuleAdapter_Process` is converting SOF's underlying buffer formats to IADK's `InputStreamBuffer` and `OutputStreamBuffer` structures.
+
+Instead of letting the module directly touch the SOF `comp_buffer` (which could change with SOF version updates), the adapter uses the abstraction APIs (`source_get_data` / `sink_get_buffer`) and wraps them:
+
+1. Request raw continuous memory pointers from `source_get_data()`.
+2. Construct an `intel_adsp::InputStreamBuffer` pointing to that continuous memory chunk.
+3. Call the IADK `processing_module_.Process()`.
+4. Release precisely the amount of consumed data using `source_release_data()`.

src/audio/module_adapter/library/README.md

@@ -0,0 +1,80 @@
+# Loadable Library & Userspace Proxy (`module_adapter/library`)
+
+The `library` directory within the module adapter manages the lifecycle and execution isolation for dynamically loaded algorithms, often referred to as "LLEXT modules" or "Userspace Modules".
+
+It acts as a secure intermediary layer between the native SOF/Zephyr kernel execution mode (supervisor mode) and the 3rd-party module running in an isolated user-mode context. By relying on Zephyr's Userspace mechanisms (`k_mem_domain`, `K_USER` threads), a faulting or misbehaving loadable extension cannot crash the entire firmware.
+
+## Architecture & Userspace Sandbox
+
+The Userspace Proxy architecture involves:
+
+- **`struct userspace_context`**: This encapsulates the memory domain (`k_mem_domain`) mapped exclusively for this module (code, rodata, BSS, and private heap memory).
+- **`user_work_item`**: A Zephyr `k_work_user` mechanism. IPC configuration commands and data processing calls are packaged into a work item and executed safely inside the memory boundaries via `userspace_proxy_worker_handler`.
+
+```mermaid
+graph TD
+    subgraph SOF Supervisor Domain
+        P["Pipeline DP Scheduler"]
+        MADP["Module Adapter Context"]
+        PROXY["Userspace Proxy (userspace_proxy_invoke)"]
+    end
+
+    subgraph Zephyr Userspace Domain
+        SYSAGENT["LLEXT System Agent"]
+        HANDLER["Worker Handler (userspace_proxy_handle_request)"]
+        MOD["External Loadable Module (struct module_interface)"]
+    end
+
+    P -->|Triggers process| MADP
+    MADP -->|Invokes Proxy| PROXY
+
+    PROXY -->|Packages params & k_work| HANDLER
+
+    HANDLER -->|Safe Call Context| MOD
+    SYSAGENT -.->|Bootstraps| MOD
+
+    style SOF Supervisor Domain fill:#1d2951,stroke:#333
+    style Zephyr Userspace Domain fill:#2e0b1a,stroke:#333
+```
+
+## State Transitions & IPC Handling
+
+IPC messages arriving from the host (e.g. `SET_CONF`, `GET_CONF`, `MODULE_INIT`, `MODULE_BIND`) first hit the Module Adapter running in Supervisor Mode. The adapter checks its configuration and invokes the Userspace Proxy. The proxy performs the following context switch:
+
+```mermaid
+sequenceDiagram
+    participant IPC as SOF IPC Task
+    participant MA as Module Adapter
+    participant Proxy as Userspace Proxy
+    participant Worker as Zephyr k_work_user Thread
+    participant UserMod as LLEXT Module
+
+    IPC->>MA: IPC SET_CONF config_id
+    MA->>Proxy: userspace_proxy_set_configuration
+
+    note over Proxy: 1. Package proxy params
+    note over Proxy: 2. Add Mailbox memory to `k_mem_domain`
+    note over Proxy: 3. Post `k_work_user` / event
+
+    Proxy->>Worker: Context Switch -> User Mode
+
+    Worker->>UserMod: module_interface set_configuration
+
+    note over UserMod: Parse config payload safely
+
+    UserMod-->>Worker: Return status
+    Worker-->>Proxy: Signal Task Done
+
+    note over Proxy: Remove Mailbox memory from domain
+
+    Proxy-->>MA: Return execution
+    MA-->>IPC: Send Reply/Status to Host
+```
+
+### Memory Domain Adjustments
+
+A crucial aspect of the userspace proxy is dynamic memory permission elevation:
+
+- Normally, the userspace module can only access its own `heap`, `data`, and `bss` partitions.
+- When an IPC like `GET_CONF` requests large IPC buffers, the proxy temporarily adds the hardware `MAILBOX_HOSTBOX` into the module's `k_mem_domain` using `k_mem_domain_add_partition()`.
+- Once the userspace thread returns, that hardware window is immediately removed from the memory domain to minimize the vulnerability window.