Refactor app loading and window management (#609)

2026-08-11 23:40:59 +02:00
parent dc3f6104b8
commit 37c507544b
243 changed files with 16034 additions and 10865 deletions
@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <app/manifest.h>
+#include <tactility/error.h>
+#include <stdint.h>
+#include "location.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** service-module id the AppLoaderApi implementation for AppManifest::location.type ==
+ * APP_LOCATION_MEMORY must register under. Implemented by app-module itself (source/app_internal_loader.cpp). */
+#define APP_LOADER_MEMORY_SERVICE_ID "app-loader-memory"
+
+/** service-module id the AppLoaderApi implementation for AppManifest::location.type ==
+ * APP_LOCATION_PATH must register under. Implemented by a platform module (e.g. app-esp32-module). */
+#define APP_LOADER_PATH_SERVICE_ID "app-loader-path"
+
+/**
+ * Entry point signature for an APP_LOCATION_MEMORY app: a function linked directly into this
+ * firmware binary. Called on the dedicated task app-module's scheduler spawns for this instance,
+ * blocking for the app's whole lifetime - same contract as an external app's main(), plus
+ * @a app_instance_id identifying this running instance (use it with
+ * app_event_subscribe()/window_manager_create()/app_manager_finish()/etc.).
+ * AppManifest::location.location holds this cast to void*.
+ */
+typedef int32_t (*AppMainFn)(uint32_t app_instance_id, int argc, char* argv[]);
+
+typedef void* AppRuntime;
+
+/**
+ * Pluggable mechanism for loading and executing an app.
+ */
+struct AppLoaderApi {
+    /**
+     * Prepares an app instance for execution (e.g. read + relocate its binary).
+     * @param[in] location the location to load the elf from
+     * @param[out] out_runtime opaque handle to whatever load() allocated; passed back to run()/unload()
+     */
+    error_t (*load)(struct AppLocation location, AppRuntime* out_runtime);
+
+    /**
+     * Blocking: runs the app to completion.
+     * @param[in] runtime handle produced by load()
+     * @param[in] app_instance_id the running instance's id
+     * @param[in] argc the amount of arguments in @a argv
+     * @param[in] argv the array of string pointers (can be NULL)
+     */
+    int32_t (*run)(AppRuntime runtime, uint32_t app_instance_id, int argc, char* argv[]);
+
+    /** Releases whatever load() allocated. Called after run() returns. */
+    void (*unload)(AppRuntime runtime);
+};
+
+#ifdef __cplusplus
+}
+#endif