Enable swappable Android kernel packages

Author: TriDefender

CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## v1.1.c21b45 - 2026-05-28
+
+- Added a dedicated Kernels screen for GitHub release discovery, compressed kernel downloads, local archive import, activation, and deletion.
+- Added kernel version metadata, persistence, bundled fallback registration, package validation, and missing-library warnings.
+- Updated downloaded kernel extraction to accept both `llama-server` and `libllama-server.so`, storing executables as `bin/libllama-server.so`.
+- Fixed Android `error=13` launch failures by launching downloaded `.so` executables through `/system/bin/linker64` and launching bundled/reverted executables from Android's native library directory.
+- Reworked kernel activation to clear stale active binaries/libraries before switching and to re-apply executable permissions whenever a kernel is activated or prepared.
+- Fixed Hexagon startup by using semicolon-separated `ADSP_LIBRARY_PATH` entries and including app, native library, RFSA, and DSP search paths.
+- Added a one-shot CPU fallback for Hexagon session-open failures so the server can recover when CDSP/HTP access fails.
+- Updated runtime detection for newer llama-server logs that report `server is listening on ...`.
+- Updated documentation for the new kernel packaging, activation, launch, and DSP library-path behavior.
+
+### Verification
+
+- Built signed release APK with `llama-android-builder:latest`.
+- Installed and launched on device `3B15AV008YH00000`.
+- Verified downloaded and bundled kernel launch paths no longer fail with `error=13`.
+- Verified HTP0 startup after the ADSP path fix: model loaded and `llama-server` listened on `http://127.0.0.1:8080`.

README.md

@@ -83,7 +83,7 @@ It also copies `bin/llama-server` as:
 app/src/main/jniLibs/arm64-v8a/libllama-server.so
 ```
 
-This rename is intentional: Android automatically packages and extracts `.so` files from `jniLibs`, so the executable is stored with a library-style filename during packaging and restored to `llama-server` at runtime.
+This rename is intentional: Android automatically packages and extracts `.so` files from `jniLibs`, so the executable is stored with a library-style filename during packaging. Bundled kernels launch directly from Android's native library directory; downloaded kernels keep the same `libllama-server.so` name and are launched through Android's dynamic linker.
 
 ## Building the APK
 
@@ -160,6 +160,7 @@ At app startup, `MainActivity` opens the Compose UI:
 MainActivity
 └── MainScreen
     ├── Config tab  -> AllConfigScreen
+    ├── Kernels tab -> KernelScreen
     └── Runtime tab -> RuntimeScreen
 ```
 
@@ -169,27 +170,28 @@ When the user starts the server:
 RuntimeScreen
 └── RuntimeViewModel.startServer()
     └── ServerProcessManager.startServer(config)
+        ├── KernelRepository.prepareActiveVersion()
         ├── BinaryExtractor.ensureAllAvailable(context)
         ├── build llama-server command line
         ├── configure process environment
         ├── ProcessBuilder(...).start()
         └── read stdout/stderr for server status
 ```
 
-`BinaryExtractor` restores runtime files under app-private storage:
+`BinaryExtractor` stages active runtime files under app-private storage:
 
 ```text
-filesDir/bin/llama-server
-filesDir/lib/*.so
+filesDir/bin/libllama-server.so  # only for downloaded kernels
+filesDir/lib/*.so                # active kernel libraries
 ```
 
-It first attempts to create symlinks from Android's extracted native library directory. If symlinking fails, it copies the files. The executable is marked with `chmod 755`.
+For bundled kernels, the process launches `libllama-server.so` directly from Android's extracted native library directory. For downloaded kernels, Android does not reliably allow direct `execve` of app-private downloaded files, so the app launches `/system/bin/linker64 filesDir/bin/libllama-server.so ...`. The staged executable is still marked with `chmod 755` each time a kernel is activated or prepared.
 
 `ServerProcessManager` configures library search paths before launching the process:
 
 ```text
-LD_LIBRARY_PATH=<filesDir>:<filesDir>/lib:/system/lib64:/system/vendor/lib64:/vendor/lib64:/vendor/dsp/cdsp
-ADSP_LIBRARY_PATH=<filesDir>/lib
+LD_LIBRARY_PATH=<filesDir>/bin:<filesDir>/lib:<nativeLibraryDir>:<filesDir>:/system/lib64:/system/vendor/lib64:/vendor/lib64:/vendor/dsp/cdsp
+ADSP_LIBRARY_PATH=<filesDir>/lib;<nativeLibraryDir>;/vendor/lib/rfsa/adsp;/system/vendor/lib/rfsa/adsp;/vendor/lib64/rfs/dsp;/vendor/dsp/cdsp;/dsp
 GGML_HEXAGON_EXPERIMENTAL=1   # for HTP devices
 ```
 
@@ -220,7 +222,7 @@ The active configuration is persisted as JSON at runtime by `ConfigRepositoryImp
 The generated command has this general shape:
 
 ```text
-filesDir/bin/llama-server
+<nativeLibraryDir>/libllama-server.so
   --model <model-path>
   --poll 1000
   --ctx-size <context-size>
@@ -240,6 +242,8 @@ filesDir/bin/llama-server
   [--predict <tokens>]
 ```
 
+Downloaded kernels use the same arguments with `/system/bin/linker64 <filesDir>/bin/libllama-server.so` as the command prefix.
+
 The app treats stdout/stderr as the process status channel. It marks the server as running when output contains messages such as `HTTP server is listening` or `llama server listening`.
 
 ## Notes and known sharp edges

app/proguard-rules.pro

@@ -5,20 +5,9 @@
 # For more details, see
 #   http://developer.android.com/guide/developing/tools/proguard.html
 
-# If your project uses WebView with JS, uncomment the following
-# and specify the fully qualified class name to the JavaScript interface
-# class:
-#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
-#   public *;
-#}
-
-# Uncomment this to preserve the line number information for
-# debugging stack traces.
-#-keepattributes SourceFile,LineNumberTable
-
-# If you keep the line number information, uncomment this to
-# hide the original source file name.
-#-renamesourcefileattribute SourceFile
+# Keep line number information for debugging stack traces
+-keepattributes SourceFile,LineNumberTable
+-renamesourcefileattribute SourceFile
 
 # Hilt
 -keep class dagger.hilt.** { *; }
@@ -41,5 +30,24 @@
 
 # Compose
 -dontnote kotlinx.coroutines.DebugKt
--keep,includedescriptorclasses class com.example.llamaserver.ui.theme.** { *; }
--keep,includedescriptorclasses class com.example.llamaserver.ui.components.** { *; }
+-keep,includedescriptorclasses class tridefender.llama.snapdragon.ui.theme.** { *; }
+
+# kotlinx.serialization
+-keepattributes *Annotation*, InnerClasses
+-dontnote kotlinx.serialization.AnnotationsKt
+-keepclassmembers class kotlinx.serialization.json.** { *** Companion; }
+-keepclasseswithmembers class kotlinx.serialization.json.** { kotlinx.serialization.KSerializer serializer(...); }
+-keep,includedescriptorclasses class tridefender.llama.snapdragon.**$$serializer { *; }
+-keepclassmembers class tridefender.llama.snapdragon.** {
+    *** Companion;
+}
+-keepclasseswithmembers class tridefender.llama.snapdragon.** {
+    kotlinx.serialization.KSerializer serializer(...);
+}
+
+# Keep model classes for serialization
+-keep class tridefender.llama.snapdragon.model.** { *; }
+-keep class tridefender.llama.snapdragon.model.KernelSource { *; }
+-keep class tridefender.llama.snapdragon.model.KernelVersion { *; }
+-keep class tridefender.llama.snapdragon.model.KernelConfig { *; }
+-keep class tridefender.llama.snapdragon.model.ServerConfig { *; }

app/src/main/java/tridefender/llama/snapdragon/di/RepositoryModule.kt

@@ -1,8 +1,10 @@
 package tridefender.llama.snapdragon.di
 
 import tridefender.llama.snapdragon.repository.ConfigRepository
+import tridefender.llama.snapdragon.repository.KernelRepository
 import tridefender.llama.snapdragon.repository.PresetRepository
 import tridefender.llama.snapdragon.repository.impl.ConfigRepositoryImpl
+import tridefender.llama.snapdragon.repository.impl.KernelRepositoryImpl
 import tridefender.llama.snapdragon.repository.impl.PresetRepositoryImpl
 import dagger.Binds
 import dagger.Module
@@ -17,7 +19,11 @@ abstract class RepositoryModule {
     @Binds
     @Singleton
     abstract fun bindConfigRepository(impl: ConfigRepositoryImpl): ConfigRepository
-    
+
+    @Binds
+    @Singleton
+    abstract fun bindKernelRepository(impl: KernelRepositoryImpl): KernelRepository
+
     @Binds
     @Singleton
     abstract fun bindPresetRepository(impl: PresetRepositoryImpl): PresetRepository

app/src/main/java/tridefender/llama/snapdragon/model/KernelVersion.kt

@@ -0,0 +1,46 @@
+package tridefender.llama.snapdragon.model
+
+import kotlinx.serialization.Serializable
+
+@Serializable
+enum class KernelSource {
+    BUNDLED,
+    GITHUB_RELEASE,
+    LOCAL_IMPORT
+}
+
+@Serializable
+data class KernelVersion(
+    val name: String,
+    val isBundled: Boolean = false,
+    val installedAt: Long = System.currentTimeMillis(),
+    val source: KernelSource = KernelSource.BUNDLED,
+    val missingLibraries: List<String> = emptyList()
+)
+
+@Serializable
+data class KernelConfig(
+    val activeVersion: String = BUNDLED_NAME,
+    val versions: List<KernelVersion> = emptyList()
+) {
+    companion object {
+        const val BUNDLED_NAME = "Optimized Defaults"
+    }
+}
+
+enum class DownloadState {
+    IDLE,
+    DOWNLOADING,
+    EXTRACTING,
+    VALIDATING,
+    DONE,
+    ERROR
+}
+
+data class GitHubRelease(
+    val tagName: String,
+    val name: String,
+    val assetName: String,
+    val assetUrl: String,
+    val assetSize: Long
+)

app/src/main/java/tridefender/llama/snapdragon/repository/KernelRepository.kt

@@ -0,0 +1,32 @@
+package tridefender.llama.snapdragon.repository
+
+import android.net.Uri
+import tridefender.llama.snapdragon.model.DownloadState
+import tridefender.llama.snapdragon.model.GitHubRelease
+import tridefender.llama.snapdragon.model.KernelConfig
+import tridefender.llama.snapdragon.model.KernelVersion
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.StateFlow
+
+interface KernelRepository {
+    val kernelConfig: StateFlow<KernelConfig>
+    val downloadState: StateFlow<DownloadState>
+    val downloadProgress: StateFlow<Float>
+
+    suspend fun ensureBundledExtracted()
+    suspend fun prepareActiveVersion(): Boolean
+    fun getActiveVersion(): String
+    fun getInstalledVersions(): List<KernelVersion>
+    suspend fun switchVersion(name: String): Boolean
+    suspend fun importLocalArchive(uri: Uri, name: String): ImportResult
+    suspend fun deleteVersion(name: String): Boolean
+    fun canDelete(name: String): Boolean
+    suspend fun fetchGitHubReleases(repoOwner: String, repoName: String): List<GitHubRelease>
+    suspend fun downloadFromGitHub(release: GitHubRelease): Flow<DownloadState>
+    suspend fun checkAndRevertIfNeeded(): String?
+}
+
+sealed class ImportResult {
+    data class Success(val missingLibraries: List<String>) : ImportResult()
+    data class Error(val message: String) : ImportResult()
+}