Implement app streams: stdio for apps

CMakeLists.txt

@@ -64,6 +64,10 @@ if (DEFINED ENV{ESP_IDF_VERSION})
         idf_build_set_property(LINK_OPTIONS "-Wl,--wrap=esp_panic_handler" APPEND)
     endif ()
 
+    idf_build_set_property(LINK_OPTIONS "-Wl,--wrap=read" APPEND)
+    idf_build_set_property(LINK_OPTIONS "-Wl,--wrap=write" APPEND)
+    idf_build_set_property(LINK_OPTIONS "-Wl,--wrap=close" APPEND)
+
     idf_build_set_property(LINK_OPTIONS "-Wl,--wrap=lv_button_create" APPEND)
     idf_build_set_property(LINK_OPTIONS "-Wl,--wrap=lv_dropdown_create" APPEND)
     idf_build_set_property(LINK_OPTIONS "-Wl,--wrap=lv_list_create" APPEND)

Modules/app-module/include/app/file.h

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <stddef.h>
+#include <stdint.h>
+#include <sys/types.h>
+
+#include <tactility/error.h>
+#include <tactility/freertos/freertos.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Which readiness condition to block for in AppFileOps::await(). */
+typedef enum {
+    APP_FILE_WAIT_READABLE,
+    APP_FILE_WAIT_WRITABLE,
+} AppFileWait;
+
+/** Bits returned by AppFileOps::poll(). */
+#define APP_FILE_READABLE (1u << 0)
+#define APP_FILE_WRITABLE (1u << 1)
+
+/**
+ * Operations table for one kind of file-like object (stream, file, device, ...). Every function
+ * takes the type-erased `object` a concrete AppFile instance was constructed with.
+ */
+struct AppFileOps {
+    ssize_t (*read)(void* object, void* buffer, size_t size);
+    ssize_t (*write)(void* object, const void* buffer, size_t size);
+    error_t (*close)(void* object);
+    error_t (*await)(void* object, AppFileWait wait, TickType_t timeout);
+    /** @return bitmask of APP_FILE_READABLE / APP_FILE_WRITABLE. */
+    uint32_t (*poll)(void* object);
+};
+
+/** A file-descriptor-table entry: an operations table paired with the object it operates on. */
+struct AppFile {
+    const struct AppFileOps* ops;
+    void* object;
+};
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/include/app/io.h

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <stddef.h>
+#include <sys/types.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define STDIN_FILENO 0
+#define STDOUT_FILENO 1
+#define STDERR_FILENO 2
+
+/** Fixed size of an app instance's fd table. FD allocation uses the lowest unused index >= 3. */
+#define APP_MAX_FDS 16
+
+/**
+ * FD-table dispatch for read()/write()/close(). When the calling task belongs to a running app
+ * instance, @a fd is looked up in that instance's own fd table; otherwise (e.g. a kernel service
+ * task) @a fd is a real underlying fd and the call falls through to the real syscall unchanged.
+ * @return number of bytes transferred, 0 on EOF (read) or a closed peer (write), or -1 with
+ * errno set on failure. This is the fd-layer translation of AppFileOps::read()/write()'s ssize_t
+ * and AppFileOps::close()'s error_t.
+ */
+ssize_t app_io_read(int fd, void* buffer, size_t size);
+ssize_t app_io_write(int fd, const void* buffer, size_t size);
+int app_io_close(int fd);
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/include/app/manager.h

@@ -3,6 +3,7 @@
 
 #include <app/instance.h>
 #include <app/manifest.h>
+#include <app/stream.h>
 
 #include <tactility/error.h>
 
@@ -86,6 +87,30 @@ error_t app_manager_start_with_parameters(const char* id, int argc, const char*
  */
 error_t app_manager_start_for_result(const char* id, AppInstanceId parent_instance_id, int argc, const char* const argv[], AppInstanceId* out_app_instance_id);
 
+/** One fd-to-stream binding for app_manager_start_with_streams(). Every field is passed through
+ * to app_stream_subscribe() as-is; see its own doc for the ownership contracts. */
+struct AppStreamBinding {
+    int producer_fd;
+    struct AppStream* stream;
+    void* buffer;
+    size_t buffer_capacity;
+    struct TaskEventGroup* event_group;
+};
+
+/**
+ * Same as app_manager_start(), but installs @a bindings into the new instance's fd table before
+ * its task begins executing (e.g. a child's stdio, piped through parent-owned AppStreams; see
+ * app/stream.h). Writes the new instance's id into each bound stream's producer_id itself, since
+ * the caller cannot know it in advance.
+ * @param[in] bindings @a binding_count entries; each stream and buffer must stay alive (see
+ * app_stream_subscribe()) until unsubscribed or the child exits.
+ * @retval ERROR_NOT_FOUND no manifest with this id is registered, or no AppLoaderApi is registered
+ * @retval ERROR_OUT_OF_RANGE a binding's producer_fd is out of range
+ * @retval ERROR_RESOURCE a binding's event_group has no free bits left to claim
+ * @retval ERROR_NONE on success
+ */
+error_t app_manager_start_with_streams(const char* id, const struct AppStreamBinding* bindings, size_t binding_count, AppInstanceId* out_app_instance_id);
+
 /**
  * Stop an app instance permanently. Emits APP_EVENT_CLOSE and bound-waits for its task to exit
  * if it was running.

Modules/app-module/include/app/stream.h

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <app/file.h>
+#include <app/instance.h>
+
+#include <stddef.h>
+#include <stdint.h>
+
+#include <tactility/concurrent/mutex.h>
+#include <tactility/concurrent/task_event_group.h>
+#include <tactility/error.h>
+#include <tactility/freertos/freertos.h>
+#include <tactility/freertos/task.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+struct AppStreamBuffer {
+    uint8_t* data;
+    size_t capacity;
+    size_t read_pos;
+    size_t write_pos;
+    size_t count;
+};
+
+/**
+ * Internal state of the stream.
+ * Buffered byte-oriented communication between one producer task and one consumer task. The
+ * consumer owns the AppStream object and its lifetime. See app_stream_subscribe().
+ * @warning `internal` is for internal use only; do not read or write its fields directly.
+ */
+struct AppStream {
+    struct {
+        struct AppStreamBuffer buffer;
+        AppInstanceId producer_id;
+        TaskHandle_t producer_task;
+        /** fd this stream is installed at in producer_id's fd table; set by
+         * app_stream_subscribe()/app_manager_start_with_streams(), used by
+         * app_stream_unsubscribe() to find it again. */
+        int producer_fd;
+
+        struct Mutex mutex;
+        /** Caller-owned group readiness is signalled on; see app_stream_subscribe(). */
+        struct TaskEventGroup* event_group;
+        uint32_t readable_bit;
+        uint32_t writable_bit;
+        bool closed;
+    } internal;
+};
+
+/**
+ * Registers @a stream as the file-like object bound to @a producer_id's fd table at
+ * @a producer_fd, claiming two bits from @a event_group for its readable/writable readiness.
+ * There is at most one subscriber for a given app fd. Subscribing over an existing one
+ * atomically closes it first (any task blocked on it wakes; already-buffered bytes remain
+ * readable until drained) and installs @a stream in its place.
+ * @param[in,out] stream caller-owned. Storage must remain valid until
+ * app_stream_unsubscribe()/app_stream_close() or app-exit teardown.
+ * @param[in] buffer ring buffer storage; caller-owned, same validity requirement as @a stream.
+ * @param[in] buffer_capacity size of @a buffer in bytes.
+ * @param[in] event_group caller-owned; must outlive @a stream (i.e. be destructed only after
+ * app_stream_unsubscribe()). Lets a task wait on this stream's readiness together with other
+ * event sources sharing the same group via task_event_group_wait()/task_event_group_wait_any().
+ * @retval ERROR_NOT_FOUND no instance with this id is running
+ * @retval ERROR_OUT_OF_RANGE @a producer_fd is out of range
+ * @retval ERROR_RESOURCE @a event_group has no free bits left to claim
+ * @retval ERROR_NONE on success
+ */
+error_t app_stream_subscribe(struct AppStream* stream, void* buffer, size_t buffer_capacity, struct TaskEventGroup* event_group, AppInstanceId producer_id, int producer_fd);
+
+/** Removes @a stream from whatever fd table it was installed in, restoring the null device there,
+ * and releases its two bits back to the event_group given to app_stream_subscribe(). */
+error_t app_stream_unsubscribe(struct AppStream* stream);
+
+/**
+ * Blocks until @a stream becomes readable/writable (per @a wait) or @a timeout elapses. Checks
+ * the current state directly before blocking, so a permanently-true condition (e.g. closed)
+ * keeps returning immediately on every call, even though the underlying event bit itself is
+ * one-shot (task_event_group_wait() clears a matched bit on exit).
+ * @retval ERROR_NONE the condition is true
+ * @retval ERROR_TIMEOUT @a timeout elapsed
+ * @retval ERROR_ISR_STATUS called from an ISR
+ */
+error_t app_stream_await(struct AppStream* stream, AppFileWait wait, TickType_t timeout);
+
+/** Non-blocking: copies up to @a buffer_size currently-available bytes out of @a stream. */
+size_t app_stream_read(struct AppStream* stream, void* buffer, size_t buffer_size);
+
+/** Non-blocking: copies up to @a buffer_size bytes into @a stream, as much as currently fits. */
+size_t app_stream_write(struct AppStream* stream, const void* buffer, size_t buffer_size);
+
+/**
+ * Marks @a stream closed: wakes any task blocked in app_stream_await(), and causes the other side
+ * to observe EOF (reader, once drained) or a write error (writer).
+ */
+error_t app_stream_close(struct AppStream* stream);
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/private/app/private/fd_table.h

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <app/file.h>
+#include <app/io.h>
+
+#include <stdbool.h>
+
+#include <tactility/concurrent/mutex.h>
+#include <tactility/error.h>
+
+/**
+ * Every app instance's fd table (see AppInstanceRecord). `slots` is the backing storage for the
+ * AppFile each in-use `fds[]` entry points to: `fds[i]` is either NULL or `&slots[i]`. `mutex`
+ * guards `fds`/`slots` only; it is never held while calling into an AppFile's ops (dispatch
+ * copies the AppFile out under the lock first), since those calls belong to independently
+ * synchronized objects (AppStream's own mutex/event group) and may run concurrently with a
+ * close()/bind() replacing an unrelated slot.
+ */
+struct AppFdTable {
+    struct AppFile slots[APP_MAX_FDS];
+    struct AppFile* fds[APP_MAX_FDS];
+    struct Mutex mutex;
+};
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** Initializes every fd to the null device (see app/private/null_device.h) and constructs `mutex`. */
+void app_fd_table_construct(struct AppFdTable* table);
+
+/** Closes every still-open fd (via AppFileOps::close()) and destructs `mutex`. */
+void app_fd_table_teardown(struct AppFdTable* table);
+
+/**
+ * Installs {ops, object} at @a fd, closing whatever was previously there first (the null device
+ * counts as "previously there" for fds 0-2, so this doubles as their initial stdio binding).
+ * @retval ERROR_OUT_OF_RANGE @a fd is outside [0, APP_MAX_FDS)
+ */
+error_t app_fd_table_bind(struct AppFdTable* table, int fd, const struct AppFileOps* ops, void* object);
+
+/**
+ * Installs {ops, object} at the lowest unused fd >= 3.
+ * @retval ERROR_RESOURCE the table is full
+ */
+error_t app_fd_table_allocate(struct AppFdTable* table, const struct AppFileOps* ops, void* object, int* out_fd);
+
+/** @return true and fills @a out_file if @a fd is currently in use, false otherwise. */
+bool app_fd_table_get(struct AppFdTable* table, int fd, struct AppFile* out_file);
+
+/**
+ * Closes @a fd (via AppFileOps::close()) and frees the slot for reuse.
+ * @retval ERROR_NOT_FOUND @a fd is out of range or not currently in use
+ */
+error_t app_fd_table_close(struct AppFdTable* table, int fd);
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/private/app/private/ledger.h

@@ -3,6 +3,7 @@
 
 #include <app/instance.h>
 #include <app/manifest.h>
+#include <app/private/fd_table.h>
 
 #include <tactility/concurrent/mutex.h>
 #include <tactility/freertos/freertos.h>
@@ -49,6 +50,10 @@ struct AppInstanceRecord {
     /** This instance's completion signal - see AppCompletionSignal. Set once by
      * app_scheduler_start(), never reassigned. */
     AppCompletionSignal* completion = nullptr;
+
+    /** This instance's fd table. Constructed by start_internal() before insertion into
+     * AppLedger::instances, torn down (every open fd closed) when the instance's task exits. */
+    AppFdTable fd_table {};
 };
 
 struct AppLedger {

Modules/app-module/private/app/private/null_device.h

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <app/file.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @return the shared null-device AppFile: write() discards data and reports success, read()
+ * reports EOF, close() is a no-op, and it is always reported readable/writable.
+ */
+const struct AppFile* app_null_file(void);
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/private/app/private/stream_internal.h

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+#pragma once
+
+#include <app/file.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/** @return the AppFileOps used for stream-backed fd table entries (see app_stream_subscribe()). */
+const struct AppFileOps* app_stream_ops(void);
+
+#ifdef __cplusplus
+}
+#endif

Modules/app-module/source/fd_table.cpp

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <app/private/fd_table.h>
+#include <app/private/null_device.h>
+
+#include <tactility/concurrent/mutex.h>
+#include <tactility/error.h>
+
+namespace {
+
+bool fd_in_range(int fd) {
+    return fd >= 0 && fd < APP_MAX_FDS;
+}
+
+} // namespace
+
+extern "C" {
+
+void app_fd_table_construct(AppFdTable* table) {
+    const AppFile* null_file = app_null_file();
+    for (int fd = 0; fd < APP_MAX_FDS; fd++) {
+        table->fds[fd] = nullptr;
+    }
+    for (int fd = STDIN_FILENO; fd <= STDERR_FILENO; fd++) {
+        table->slots[fd] = *null_file;
+        table->fds[fd] = &table->slots[fd];
+    }
+    mutex_construct(&table->mutex);
+}
+
+void app_fd_table_teardown(AppFdTable* table) {
+    for (int fd = 0; fd < APP_MAX_FDS; fd++) {
+        if (table->fds[fd] != nullptr) {
+            table->slots[fd].ops->close(table->slots[fd].object);
+            table->fds[fd] = nullptr;
+        }
+    }
+    mutex_destruct(&table->mutex);
+}
+
+error_t app_fd_table_bind(AppFdTable* table, int fd, const AppFileOps* ops, void* object) {
+    if (!fd_in_range(fd)) {
+        return ERROR_OUT_OF_RANGE;
+    }
+
+    mutex_lock(&table->mutex);
+    AppFile old = table->slots[fd];
+    bool had_old = table->fds[fd] != nullptr;
+    table->slots[fd] = { .ops = ops, .object = object };
+    table->fds[fd] = &table->slots[fd];
+    mutex_unlock(&table->mutex);
+
+    if (had_old) {
+        old.ops->close(old.object);
+    }
+    return ERROR_NONE;
+}
+
+error_t app_fd_table_allocate(AppFdTable* table, const AppFileOps* ops, void* object, int* out_fd) {
+    mutex_lock(&table->mutex);
+    for (int fd = 3; fd < APP_MAX_FDS; fd++) {
+        if (table->fds[fd] == nullptr) {
+            table->slots[fd] = { .ops = ops, .object = object };
+            table->fds[fd] = &table->slots[fd];
+            mutex_unlock(&table->mutex);
+            *out_fd = fd;
+            return ERROR_NONE;
+        }
+    }
+    mutex_unlock(&table->mutex);
+    return ERROR_RESOURCE;
+}
+
+bool app_fd_table_get(AppFdTable* table, int fd, AppFile* out_file) {
+    if (!fd_in_range(fd)) {
+        return false;
+    }
+
+    mutex_lock(&table->mutex);
+    bool in_use = table->fds[fd] != nullptr;
+    if (in_use) {
+        *out_file = table->slots[fd];
+    }
+    mutex_unlock(&table->mutex);
+    return in_use;
+}
+
+error_t app_fd_table_close(AppFdTable* table, int fd) {
+    if (!fd_in_range(fd)) {
+        return ERROR_NOT_FOUND;
+    }
+
+    mutex_lock(&table->mutex);
+    bool in_use = table->fds[fd] != nullptr;
+    AppFile old = table->slots[fd];
+    table->fds[fd] = nullptr;
+    mutex_unlock(&table->mutex);
+
+    if (!in_use) {
+        return ERROR_NOT_FOUND;
+    }
+    return old.ops->close(old.object);
+}
+
+} // extern "C"

Modules/app-module/source/io.cpp

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <app/io.h>
+
+#include <app/private/fd_table.h>
+#include <app/private/ledger.h>
+#include <app/scheduler.h>
+
+#include <cerrno>
+
+#ifdef ESP_PLATFORM
+extern "C" {
+ssize_t __real_read(int fd, void* buffer, size_t size);
+ssize_t __real_write(int fd, const void* buffer, size_t size);
+int __real_close(int fd);
+}
+#else
+#include <unistd.h>
+#endif
+
+namespace {
+
+// NULL for a caller not running as an app instance (e.g. a kernel service task). @a fd is then
+// a real underlying fd, handled by the caller falling through to the real syscall.
+AppFdTable* current_app_fd_table() {
+    AppInstanceId app_id = app_scheduler_current_app_id();
+    if (app_id == 0) {
+        return nullptr;
+    }
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    auto iterator = ledger.instances.find(app_id);
+    AppFdTable* table = (iterator != ledger.instances.end()) ? &iterator->second.fd_table : nullptr;
+    mutex_unlock(&ledger.mutex);
+    return table;
+}
+
+} // namespace
+
+extern "C" {
+
+ssize_t app_io_read(int fd, void* buffer, size_t size) {
+    AppFdTable* table = current_app_fd_table();
+    if (table == nullptr) {
+#ifdef ESP_PLATFORM
+        return __real_read(fd, buffer, size);
+#else
+        return ::read(fd, buffer, size);
+#endif
+    }
+
+    AppFile file {};
+    if (!app_fd_table_get(table, fd, &file)) {
+        errno = EBADF;
+        return -1;
+    }
+    return file.ops->read(file.object, buffer, size);
+}
+
+ssize_t app_io_write(int fd, const void* buffer, size_t size) {
+    AppFdTable* table = current_app_fd_table();
+    if (table == nullptr) {
+#ifdef ESP_PLATFORM
+        return __real_write(fd, buffer, size);
+#else
+        return ::write(fd, buffer, size);
+#endif
+    }
+
+    AppFile file {};
+    if (!app_fd_table_get(table, fd, &file)) {
+        errno = EBADF;
+        return -1;
+    }
+    return file.ops->write(file.object, buffer, size);
+}
+
+int app_io_close(int fd) {
+    AppFdTable* table = current_app_fd_table();
+    if (table == nullptr) {
+#ifdef ESP_PLATFORM
+        return __real_close(fd);
+#else
+        return ::close(fd);
+#endif
+    }
+
+    if (app_fd_table_close(table, fd) != ERROR_NONE) {
+        errno = EBADF;
+        return -1;
+    }
+    return 0;
+}
+
+} // extern "C"

Modules/app-module/source/manager.cpp

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 #include <app/manager.h>
 #include <app/metadata.h>
+#include <app/private/fd_table.h>
 #include <app/private/fs.h>
 #include <app/private/ledger.h>
 #include <app/private/scheduler.h>
@@ -89,8 +90,10 @@ char** copy_arguments(int argc, const char* const argv[]) {
 
 // Takes ownership of argv (already a deep copy, or NULL/argc==0) regardless of outcome -
 // app_scheduler_start() frees it on any failure path, and the spawned task frees it once its
-// run() returns.
-error_t start_internal(const char* id, AppInstanceId parent_instance_id, int argc, char* argv[], AppInstanceId* out_app_instance_id) {
+// run() returns. @a bindings (@a binding_count entries, may be NULL/0) are subscribed into the
+// new instance's fd table before app_scheduler_start() is called, so they're in place before its
+// task begins executing (see app_manager_start_with_streams()).
+error_t start_internal(const char* id, AppInstanceId parent_instance_id, int argc, char* argv[], const AppStreamBinding* bindings, size_t binding_count, AppInstanceId* out_app_instance_id) {
     auto& ledger = app_ledger();
 
     mutex_lock(&ledger.mutex);
@@ -106,13 +109,31 @@ error_t start_internal(const char* id, AppInstanceId parent_instance_id, int arg
     AppInstanceRecord record { .id = target_id, .manifest = manifest, .state = APP_INSTANCE_STATE_STARTING, .task = nullptr };
     record.parent_id = parent_instance_id;
     ledger.instances[target_id] = record;
+    // Constructed on the map-resident copy, not the local `record` about to go out of scope.
+    // AppFdTable::fds[] entries point into AppFdTable::slots[] by address (see fd_table.h), so
+    // constructing before the copy above would leave them pointing at stack storage.
+    app_fd_table_construct(&ledger.instances[target_id].fd_table);
     mutex_unlock(&ledger.mutex);
 
     LOG_I(TAG, "[instance %d] starting %s with parent %d", target_id, manifest->id, parent_instance_id);
 
+    for (size_t i = 0; i < binding_count; i++) {
+        error_t bind_result = app_stream_subscribe(bindings[i].stream, bindings[i].buffer, bindings[i].buffer_capacity, bindings[i].event_group, target_id, bindings[i].producer_fd);
+        if (bind_result != ERROR_NONE) {
+            LOG_E(TAG, "[instance %d] Failed to bind stream at fd %d: %s", target_id, bindings[i].producer_fd, error_to_string(bind_result));
+            mutex_lock(&ledger.mutex);
+            app_fd_table_teardown(&ledger.instances[target_id].fd_table);
+            ledger.instances.erase(target_id);
+            mutex_unlock(&ledger.mutex);
+            app_ledger_free_arguments(argc, argv);
+            return bind_result;
+        }
+    }
+
     error_t error = app_scheduler_start(target_id, manifest->location, manifest->stack, argc, argv);
     if (error != ERROR_NONE) {
         mutex_lock(&ledger.mutex);
+        app_fd_table_teardown(&ledger.instances[target_id].fd_table);
         ledger.instances.erase(target_id);
         mutex_unlock(&ledger.mutex);
         LOG_I(TAG, "[instance %d] Failed to start: %s", target_id, error_to_string(error));
@@ -126,15 +147,19 @@ error_t start_internal(const char* id, AppInstanceId parent_instance_id, int arg
 } // namespace
 
 error_t app_manager_start(const char* id, AppInstanceId* out_app_instance_id) {
-    return start_internal(id, 0, 0, nullptr, out_app_instance_id);
+    return start_internal(id, 0, 0, nullptr, nullptr, 0, out_app_instance_id);
 }
 
 error_t app_manager_start_with_parameters(const char* id, int argc, const char* const argv[], AppInstanceId* out_app_instance_id) {
-    return start_internal(id, 0, argc, copy_arguments(argc, argv), out_app_instance_id);
+    return start_internal(id, 0, argc, copy_arguments(argc, argv), nullptr, 0, out_app_instance_id);
 }
 
 error_t app_manager_start_for_result(const char* id, AppInstanceId parent_instance_id, int argc, const char* const argv[], AppInstanceId* out_app_instance_id) {
-    return start_internal(id, parent_instance_id, argc, copy_arguments(argc, argv), out_app_instance_id);
+    return start_internal(id, parent_instance_id, argc, copy_arguments(argc, argv), nullptr, 0, out_app_instance_id);
+}
+
+error_t app_manager_start_with_streams(const char* id, const AppStreamBinding* bindings, size_t binding_count, AppInstanceId* out_app_instance_id) {
+    return start_internal(id, 0, 0, nullptr, bindings, binding_count, out_app_instance_id);
 }
 
 error_t app_manager_stop(AppInstanceId app_instance_id) {

Modules/app-module/source/module.cpp

@@ -1,11 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
 #include <app/event.h>
 #include <app/install.h>
+#include <app/io.h>
 #include <app/manager.h>
 #include <app/manifest.h>
 #include <app/metadata.h>
 #include <app/paths.h>
 #include <app/scheduler.h>
+#include <app/stream.h>
 
 #include <service/manager.h>
 
@@ -27,10 +29,15 @@ static const ModuleSymbol SYMBOLS[] = {
     DEFINE_MODULE_SYMBOL(app_get_install_path),
     DEFINE_MODULE_SYMBOL(app_install),
     DEFINE_MODULE_SYMBOL(app_uninstall),
+    // app/io
+    DEFINE_MODULE_SYMBOL(app_io_read),
+    DEFINE_MODULE_SYMBOL(app_io_write),
+    DEFINE_MODULE_SYMBOL(app_io_close),
     // app/manager
     DEFINE_MODULE_SYMBOL(app_manager_start),
     DEFINE_MODULE_SYMBOL(app_manager_start_with_parameters),
     DEFINE_MODULE_SYMBOL(app_manager_start_for_result),
+    DEFINE_MODULE_SYMBOL(app_manager_start_with_streams),
     DEFINE_MODULE_SYMBOL(app_manager_stop),
     DEFINE_MODULE_SYMBOL(app_manager_get_state),
     DEFINE_MODULE_SYMBOL(app_manager_find_manifest),
@@ -53,6 +60,13 @@ static const ModuleSymbol SYMBOLS[] = {
     DEFINE_MODULE_SYMBOL(app_paths_get_assets_path),
     // app/scheduler
     DEFINE_MODULE_SYMBOL(app_scheduler_current_app_id),
+    // app/stream
+    DEFINE_MODULE_SYMBOL(app_stream_subscribe),
+    DEFINE_MODULE_SYMBOL(app_stream_unsubscribe),
+    DEFINE_MODULE_SYMBOL(app_stream_await),
+    DEFINE_MODULE_SYMBOL(app_stream_read),
+    DEFINE_MODULE_SYMBOL(app_stream_write),
+    DEFINE_MODULE_SYMBOL(app_stream_close),
     // terminator
     MODULE_SYMBOL_TERMINATOR,
 };

Modules/app-module/source/null_device.cpp

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <app/private/null_device.h>
+
+namespace {
+
+ssize_t null_read(void*, void*, size_t) {
+    return 0; // EOF
+}
+
+ssize_t null_write(void*, const void* buffer, size_t size) {
+    (void)buffer;
+    return static_cast<ssize_t>(size); // discarded, reported as fully written
+}
+
+error_t null_close(void*) {
+    return ERROR_NONE;
+}
+
+error_t null_await(void*, AppFileWait, TickType_t) {
+    return ERROR_NONE; // always ready
+}
+
+uint32_t null_poll(void*) {
+    return APP_FILE_READABLE | APP_FILE_WRITABLE;
+}
+
+const AppFileOps NULL_OPS = {
+    .read = null_read,
+    .write = null_write,
+    .close = null_close,
+    .await = null_await,
+    .poll = null_poll,
+};
+
+constexpr AppFile NULL_FILE = { .ops = &NULL_OPS, .object = nullptr };
+
+} // namespace
+
+extern "C" {
+
+const AppFile* app_null_file(void) {
+    return &NULL_FILE;
+}
+
+} // extern "C"

Modules/app-module/source/scheduler.cpp

@@ -2,9 +2,12 @@
 #include <app/instance.h>
 #include <app/loader.h>
 #include <app/private/event.h>
+#include <app/private/fd_table.h>
 #include <app/private/ledger.h>
 #include <app/private/scheduler.h>
+#include <app/private/stream_internal.h>
 #include <app/scheduler.h>
+#include <app/stream.h>
 
 #include <service/instance.h>
 #include <service/manager.h>
@@ -98,6 +101,14 @@ void set_task(AppInstanceId app_instance_id, TaskHandle_t task) {
     auto iterator = ledger.instances.find(app_instance_id);
     if (iterator != ledger.instances.end()) {
         iterator->second.task = task;
+        // Streams bound before this instance's task existed (app_manager_start_with_streams())
+        // only got producer_task filled in as NULL at subscribe time. Backfill it now.
+        AppFdTable& fd_table = iterator->second.fd_table;
+        for (auto* file : fd_table.fds) {
+            if (file != nullptr && file->ops == app_stream_ops()) {
+                static_cast<AppStream*>(file->object)->internal.producer_task = task;
+            }
+        }
     }
     mutex_unlock(&ledger.mutex);
 }
@@ -218,8 +229,14 @@ void app_task_main(void* context) {
     // Erase the ledger entry before self-deleting - see "Reap self-terminated app tasks":
     // nothing else is guaranteed to ever call app_scheduler_stop() for this instance (the
     // common case is the app just closing itself), so this can't wait for that to happen.
+    // Every non-null fd is closed here too. Stream-backed entries wake/mark closed whoever is
+    // on the other end (e.g. a parent reading this instance's stdout).
     auto& ledger = app_ledger();
     mutex_lock(&ledger.mutex);
+    auto fd_table_iterator = ledger.instances.find(app_instance_id);
+    if (fd_table_iterator != ledger.instances.end()) {
+        app_fd_table_teardown(&fd_table_iterator->second.fd_table);
+    }
     ledger.instances.erase(app_instance_id);
     mutex_unlock(&ledger.mutex);
 

Modules/app-module/source/stream.cpp

@@ -0,0 +1,233 @@
+// SPDX-License-Identifier: Apache-2.0
+#include <app/stream.h>
+
+#include <app/private/fd_table.h>
+#include <app/private/ledger.h>
+#include <app/private/stream_internal.h>
+
+#include <tactility/concurrent/mutex.h>
+#include <tactility/error.h>
+
+namespace {
+
+// Caller must hold stream->internal.mutex.
+bool is_readable_locked(AppStream* stream) {
+    return stream->internal.buffer.count > 0 || stream->internal.closed;
+}
+
+// Caller must hold stream->internal.mutex.
+bool is_writable_locked(AppStream* stream) {
+    return stream->internal.buffer.count < stream->internal.buffer.capacity || stream->internal.closed;
+}
+
+ssize_t stream_file_read(void* object, void* buffer, size_t size) {
+    auto* stream = static_cast<AppStream*>(object);
+    while (true) {
+        if (app_stream_await(stream, APP_FILE_WAIT_READABLE, portMAX_DELAY) != ERROR_NONE) {
+            return -1;
+        }
+        size_t read = app_stream_read(stream, buffer, size);
+        if (read > 0) {
+            return static_cast<ssize_t>(read);
+        }
+        mutex_lock(&stream->internal.mutex);
+        bool is_closed = stream->internal.closed;
+        mutex_unlock(&stream->internal.mutex);
+        if (is_closed) {
+            return 0; // EOF: readable-because-closed, and nothing left buffered
+        }
+        // Woke readable but another party drained it first. Re-await rather than assume EOF;
+        // this is a defensive fallback since AppStream expects a single reader.
+    }
+}
+
+ssize_t stream_file_write(void* object, const void* buffer, size_t size) {
+    auto* stream = static_cast<AppStream*>(object);
+    if (app_stream_await(stream, APP_FILE_WAIT_WRITABLE, portMAX_DELAY) != ERROR_NONE) {
+        return -1;
+    }
+    mutex_lock(&stream->internal.mutex);
+    bool is_closed = stream->internal.closed;
+    mutex_unlock(&stream->internal.mutex);
+    if (is_closed) {
+        return -1; // broken pipe: woke writable only because the consumer closed
+    }
+    return static_cast<ssize_t>(app_stream_write(stream, buffer, size));
+}
+
+error_t stream_file_close(void* object) {
+    return app_stream_close(static_cast<AppStream*>(object));
+}
+
+error_t stream_file_await(void* object, AppFileWait wait, TickType_t timeout) {
+    return app_stream_await(static_cast<AppStream*>(object), wait, timeout);
+}
+
+uint32_t stream_file_poll(void* object) {
+    auto* stream = static_cast<AppStream*>(object);
+    mutex_lock(&stream->internal.mutex);
+    uint32_t bits = 0;
+    if (is_readable_locked(stream)) {
+        bits |= APP_FILE_READABLE;
+    }
+    if (is_writable_locked(stream)) {
+        bits |= APP_FILE_WRITABLE;
+    }
+    mutex_unlock(&stream->internal.mutex);
+    return bits;
+}
+
+constexpr AppFileOps STREAM_OPS = {
+    .read = stream_file_read,
+    .write = stream_file_write,
+    .close = stream_file_close,
+    .await = stream_file_await,
+    .poll = stream_file_poll,
+};
+
+} // namespace
+
+extern "C" {
+
+const AppFileOps* app_stream_ops(void) {
+    return &STREAM_OPS;
+}
+
+error_t app_stream_subscribe(AppStream* stream, void* buffer, size_t buffer_capacity, TaskEventGroup* event_group, AppInstanceId producer_id, int producer_fd) {
+    if (producer_fd < 0 || producer_fd >= APP_MAX_FDS) {
+        return ERROR_OUT_OF_RANGE;
+    }
+
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    auto iterator = ledger.instances.find(producer_id);
+    if (iterator == ledger.instances.end()) {
+        mutex_unlock(&ledger.mutex);
+        return ERROR_NOT_FOUND;
+    }
+    TaskHandle_t producer_task = iterator->second.task;
+    AppFdTable* table = &iterator->second.fd_table;
+    mutex_unlock(&ledger.mutex);
+
+    uint32_t readable_bit;
+    error_t claim_result = task_event_group_claim_bit(event_group, &readable_bit);
+    if (claim_result != ERROR_NONE) {
+        return claim_result;
+    }
+    uint32_t writable_bit;
+    claim_result = task_event_group_claim_bit(event_group, &writable_bit);
+    if (claim_result != ERROR_NONE) {
+        task_event_group_release_bit(event_group, readable_bit);
+        return claim_result;
+    }
+
+    stream->internal.producer_id = producer_id;
+    stream->internal.producer_fd = producer_fd;
+    stream->internal.producer_task = producer_task;
+    stream->internal.event_group = event_group;
+    stream->internal.readable_bit = readable_bit;
+    stream->internal.writable_bit = writable_bit;
+    stream->internal.buffer.data = static_cast<uint8_t*>(buffer);
+    stream->internal.buffer.capacity = buffer_capacity;
+    stream->internal.buffer.read_pos = 0;
+    stream->internal.buffer.write_pos = 0;
+    stream->internal.buffer.count = 0;
+    stream->internal.closed = false;
+    mutex_construct(&stream->internal.mutex);
+
+    error_t bind_result = app_fd_table_bind(table, producer_fd, &STREAM_OPS, stream);
+    if (bind_result != ERROR_NONE) {
+        mutex_destruct(&stream->internal.mutex);
+        task_event_group_release_bit(event_group, readable_bit);
+        task_event_group_release_bit(event_group, writable_bit);
+    }
+    return bind_result;
+}
+
+error_t app_stream_unsubscribe(AppStream* stream) {
+    auto& ledger = app_ledger();
+    mutex_lock(&ledger.mutex);
+    auto iterator = ledger.instances.find(stream->internal.producer_id);
+    AppFdTable* table = (iterator != ledger.instances.end()) ? &iterator->second.fd_table : nullptr;
+    mutex_unlock(&ledger.mutex);
+
+    if (table != nullptr) {
+        AppFile current {};
+        if (app_fd_table_get(table, stream->internal.producer_fd, &current) && current.object == stream) {
+            app_fd_table_close(table, stream->internal.producer_fd); // -> stream_file_close() -> app_stream_close()
+        }
+    }
+
+    app_stream_close(stream); // idempotent; covers the case where the producer already exited
+    task_event_group_release_bit(stream->internal.event_group, stream->internal.readable_bit);
+    task_event_group_release_bit(stream->internal.event_group, stream->internal.writable_bit);
+    mutex_destruct(&stream->internal.mutex);
+    return ERROR_NONE;
+}
+
+error_t app_stream_await(AppStream* stream, AppFileWait wait, TickType_t timeout) {
+    mutex_lock(&stream->internal.mutex);
+    bool ready = (wait == APP_FILE_WAIT_READABLE) ? is_readable_locked(stream) : is_writable_locked(stream);
+    mutex_unlock(&stream->internal.mutex);
+    if (ready) {
+        return ERROR_NONE;
+    }
+
+    uint32_t bit = (wait == APP_FILE_WAIT_READABLE) ? stream->internal.readable_bit : stream->internal.writable_bit;
+    return task_event_group_wait(stream->internal.event_group, bit, /*await_all=*/false, nullptr, timeout);
+}
+
+size_t app_stream_read(AppStream* stream, void* buffer, size_t buffer_size) {
+    mutex_lock(&stream->internal.mutex);
+    AppStreamBuffer& ring = stream->internal.buffer;
+    size_t to_copy = buffer_size < ring.count ? buffer_size : ring.count;
+    for (size_t i = 0; i < to_copy; i++) {
+        static_cast<uint8_t*>(buffer)[i] = ring.data[(ring.read_pos + i) % ring.capacity];
+    }
+    if (ring.capacity > 0) {
+        ring.read_pos = (ring.read_pos + to_copy) % ring.capacity;
+    }
+    ring.count -= to_copy;
+    TaskEventGroup* event_group = stream->internal.event_group;
+    uint32_t writable_bit = stream->internal.writable_bit;
+    mutex_unlock(&stream->internal.mutex);
+    if (to_copy > 0) {
+        task_event_group_signal(event_group, writable_bit); // space freed up
+    }
+    return to_copy;
+}
+
+size_t app_stream_write(AppStream* stream, const void* buffer, size_t buffer_size) {
+    mutex_lock(&stream->internal.mutex);
+    AppStreamBuffer& ring = stream->internal.buffer;
+    size_t available = ring.capacity - ring.count;
+    size_t to_copy = buffer_size < available ? buffer_size : available;
+    for (size_t i = 0; i < to_copy; i++) {
+        ring.data[(ring.write_pos + i) % ring.capacity] = static_cast<const uint8_t*>(buffer)[i];
+    }
+    if (ring.capacity > 0) {
+        ring.write_pos = (ring.write_pos + to_copy) % ring.capacity;
+    }
+    ring.count += to_copy;
+    TaskEventGroup* event_group = stream->internal.event_group;
+    uint32_t readable_bit = stream->internal.readable_bit;
+    mutex_unlock(&stream->internal.mutex);
+    if (to_copy > 0) {
+        task_event_group_signal(event_group, readable_bit); // data became available
+    }
+    return to_copy;
+}
+
+error_t app_stream_close(AppStream* stream) {
+    mutex_lock(&stream->internal.mutex);
+    stream->internal.closed = true;
+    TaskEventGroup* event_group = stream->internal.event_group;
+    uint32_t readable_bit = stream->internal.readable_bit;
+    uint32_t writable_bit = stream->internal.writable_bit;
+    mutex_unlock(&stream->internal.mutex);
+    task_event_group_signal(event_group, readable_bit);
+    task_event_group_signal(event_group, writable_bit);
+    return ERROR_NONE;
+}
+
+} // extern "C"

Modules/app-module/tests/source/io_test.cpp

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: Apache-2.0
+#include "doctest.h"
+
+#include <app/io.h>
+#include <app/loader.h>
+#include <app/manager.h>
+#include <app/scheduler.h>
+#include <app/stream.h>
+
+#include <service/manager.h>
+
+#include <tactility/delay.h>
+
+#include <atomic>
+#include <cstring>
+#include <vector>
+
+extern ServiceManifest app_internal_loader_service_manifest;
+
+namespace {
+
+// See manager_test.cpp's own copy of this helper for why this checks the registry directly
+// rather than a per-translation-unit static bool.
+void ensure_memory_loader_registered() {
+    if (service_manager_find_instance(APP_LOADER_MEMORY_SERVICE_ID) == nullptr) {
+        service_manager_add(&app_internal_loader_service_manifest, /*auto_start=*/true);
+    }
+}
+
+bool wait_for_state(AppInstanceId id, AppInstanceState target, uint32_t timeout_ms) {
+    uint32_t waited = 0;
+    while (waited < timeout_ms) {
+        if (app_manager_get_state(id) == target) {
+            return true;
+        }
+        delay_millis(10);
+        waited += 10;
+    }
+    return app_manager_get_state(id) == target;
+}
+
+std::atomic<ssize_t> g_stdio_write_result { -2 };
+std::atomic<ssize_t> g_stdio_read_result { -2 };
+
+int32_t unbound_stdio_app_main(int, char*[]) {
+    g_stdio_write_result.store(app_io_write(STDOUT_FILENO, "x", 1), std::memory_order_release);
+    uint8_t buffer[1];
+    g_stdio_read_result.store(app_io_read(STDIN_FILENO, buffer, sizeof(buffer)), std::memory_order_release);
+    return 0;
+}
+
+int32_t stdout_writer_app_main(int, char*[]) {
+    const char message[] = "hello";
+    size_t sent = 0;
+    while (sent < sizeof(message) - 1) {
+        ssize_t written = app_io_write(STDOUT_FILENO, message + sent, sizeof(message) - 1 - sent);
+        if (written < 0) {
+            break;
+        }
+        sent += static_cast<size_t>(written);
+    }
+    return 0;
+}
+
+std::atomic<bool> g_blocked_writer_saw_error { false };
+std::atomic<bool> g_blocked_writer_done { false };
+
+int32_t blocked_writer_app_main(int, char*[]) {
+    const char message[] = "0123456789"; // larger than the test's 4-byte stream capacity
+    size_t sent = 0;
+    while (sent < sizeof(message) - 1) {
+        ssize_t written = app_io_write(STDOUT_FILENO, message + sent, sizeof(message) - 1 - sent);
+        if (written < 0) {
+            g_blocked_writer_saw_error.store(true, std::memory_order_release);
+            break;
+        }
+        sent += static_cast<size_t>(written);
+    }
+    g_blocked_writer_done.store(true, std::memory_order_release);
+    return 0;
+}
+
+} // namespace
+
+TEST_CASE("an app's stdio fds default to the null device: write succeeds and discards, read reports EOF") {
+    ensure_memory_loader_registered();
+    g_stdio_write_result.store(-2, std::memory_order_relaxed);
+    g_stdio_read_result.store(-2, std::memory_order_relaxed);
+
+    AppManifest manifest { "test.io.unbound", "Unbound", APP_CATEGORY_USER, { APP_LOCATION_MEMORY, reinterpret_cast<void*>(unbound_stdio_app_main) } };
+    REQUIRE_EQ(app_manager_add(&manifest), ERROR_NONE);
+
+    AppInstanceId instance_id = 0;
+    REQUIRE_EQ(app_manager_start("test.io.unbound", &instance_id), ERROR_NONE);
+    REQUIRE(wait_for_state(instance_id, APP_INSTANCE_STATE_STOPPED, 1000));
+
+    CHECK_EQ(g_stdio_write_result.load(std::memory_order_acquire), 1);
+    CHECK_EQ(g_stdio_read_result.load(std::memory_order_acquire), 0);
+
+    app_manager_remove("test.io.unbound");
+}
+
+TEST_CASE("app_manager_start_with_streams pipes a child's app_io_write() calls into a parent-owned AppStream, EOF at exit") {
+    ensure_memory_loader_registered();
+
+    AppManifest manifest { "test.io.writer", "Writer", APP_CATEGORY_USER, { APP_LOCATION_MEMORY, reinterpret_cast<void*>(stdout_writer_app_main) } };
+    REQUIRE_EQ(app_manager_add(&manifest), ERROR_NONE);
+
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
+    uint8_t storage[64];
+    AppStream child_stdout {};
+
+    AppStreamBinding binding { STDOUT_FILENO, &child_stdout, storage, sizeof(storage), &event_group };
+    AppInstanceId child_id = 0;
+    REQUIRE_EQ(app_manager_start_with_streams("test.io.writer", &binding, 1, &child_id), ERROR_NONE);
+
+    std::vector<uint8_t> received;
+    while (app_stream_await(&child_stdout, APP_FILE_WAIT_READABLE, pdMS_TO_TICKS(1000)) == ERROR_NONE) {
+        uint8_t chunk[16];
+        size_t n = app_stream_read(&child_stdout, chunk, sizeof(chunk));
+        if (n == 0) {
+            break; // EOF
+        }
+        received.insert(received.end(), chunk, chunk + n);
+    }
+
+    REQUIRE_EQ(received.size(), 5u);
+    CHECK_EQ(std::memcmp(received.data(), "hello", 5), 0);
+
+    REQUIRE(wait_for_state(child_id, APP_INSTANCE_STATE_STOPPED, 1000));
+    app_stream_unsubscribe(&child_stdout);
+    task_event_group_destruct(&event_group);
+    app_manager_remove("test.io.writer");
+}
+
+TEST_CASE("a write blocked on a full stream wakes with an error once the consumer closes it") {
+    ensure_memory_loader_registered();
+    g_blocked_writer_saw_error.store(false, std::memory_order_relaxed);
+    g_blocked_writer_done.store(false, std::memory_order_relaxed);
+
+    AppManifest manifest { "test.io.blocked", "Blocked", APP_CATEGORY_USER, { APP_LOCATION_MEMORY, reinterpret_cast<void*>(blocked_writer_app_main) } };
+    REQUIRE_EQ(app_manager_add(&manifest), ERROR_NONE);
+
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
+    uint8_t storage[4]; // smaller than the 10 bytes blocked_writer_app_main sends
+    AppStream child_stdout {};
+
+    AppStreamBinding binding { STDOUT_FILENO, &child_stdout, storage, sizeof(storage), &event_group };
+    AppInstanceId child_id = 0;
+    REQUIRE_EQ(app_manager_start_with_streams("test.io.blocked", &binding, 1, &child_id), ERROR_NONE);
+
+    // Never drained: the child fills the 4-byte buffer and blocks awaiting space for the rest.
+    delay_millis(200);
+    CHECK_FALSE(g_blocked_writer_done.load(std::memory_order_acquire));
+
+    // Unblocks the writer without touching child_stdout's sync primitives, safe even while it
+    // may still be blocked in app_stream_await() (unlike app_stream_unsubscribe()).
+    app_stream_close(&child_stdout);
+
+    REQUIRE(wait_for_state(child_id, APP_INSTANCE_STATE_STOPPED, 1000));
+    CHECK(g_blocked_writer_saw_error.load(std::memory_order_acquire));
+
+    // Only safe now that the child's task (the only other party that could be blocked on this
+    // stream) has fully exited.
+    app_stream_unsubscribe(&child_stdout);
+    task_event_group_destruct(&event_group);
+    app_manager_remove("test.io.blocked");
+}

Modules/app-module/tests/source/manager_test.cpp

@@ -128,12 +128,12 @@ void ensure_fake_loader_registered() {
 
 // app-module's real APP_LOCATION_MEMORY loader (source/app_internal_loader.cpp) - not a fake,
 // since it has no platform dependency and is exactly what a statically-linked app would go
-// through.
+// through. Checks the registry directly rather than a per-translation-unit static bool: other
+// test files (stream_test.cpp, io_test.cpp) register the same manifest the same way, and
+// doctest doesn't guarantee which file's tests run first.
 void ensure_memory_loader_registered() {
-    static bool registered = false;
-    if (!registered) {
-        CHECK_EQ(service_manager_add(&app_internal_loader_service_manifest, /*auto_start=*/true), ERROR_NONE);
-        registered = true;
+    if (service_manager_find_instance(APP_LOADER_MEMORY_SERVICE_ID) == nullptr) {
+        service_manager_add(&app_internal_loader_service_manifest, /*auto_start=*/true);
     }
 }
 

Modules/app-module/tests/source/stream_test.cpp

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: Apache-2.0
+#include "doctest.h"
+
+#include <app/event.h>
+#include <app/loader.h>
+#include <app/manager.h>
+#include <app/scheduler.h>
+#include <app/stream.h>
+
+#include <service/manager.h>
+
+#include <tactility/delay.h>
+
+#include <cstring>
+
+extern ServiceManifest app_internal_loader_service_manifest;
+
+namespace {
+
+// See manager_test.cpp's own copy of this helper for why this checks the registry directly
+// rather than a per-translation-unit static bool.
+void ensure_memory_loader_registered() {
+    if (service_manager_find_instance(APP_LOADER_MEMORY_SERVICE_ID) == nullptr) {
+        service_manager_add(&app_internal_loader_service_manifest, /*auto_start=*/true);
+    }
+}
+
+// Stays Active, doing nothing, until asked to close. Just an anchor instance for
+// app_stream_subscribe() to target; the tests below drive the resulting AppStream directly from
+// the test thread, the same way a parent consumes a child's stream without going through its
+// own fd table.
+int32_t idle_app_main(int, char*[]) {
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
+    AppEventSubscription sub {};
+    app_event_subscribe(&sub, &event_group);
+
+    while (true) {
+        if (task_event_group_wait_any(&event_group, nullptr, pdMS_TO_TICKS(5000)) != ERROR_NONE) {
+            break; // safety net
+        }
+        bool done = false;
+        AppEvent event {};
+        while (app_event_poll(&sub, &event) == ERROR_NONE) {
+            if (event.type == APP_EVENT_CLOSE) {
+                done = true;
+                break;
+            }
+        }
+        if (done) {
+            break;
+        }
+    }
+
+    app_event_unsubscribe(&sub);
+    task_event_group_destruct(&event_group);
+    return 0;
+}
+
+bool wait_for_state(AppInstanceId id, AppInstanceState target, uint32_t timeout_ms) {
+    uint32_t waited = 0;
+    while (waited < timeout_ms) {
+        if (app_manager_get_state(id) == target) {
+            return true;
+        }
+        delay_millis(10);
+        waited += 10;
+    }
+    return app_manager_get_state(id) == target;
+}
+
+AppInstanceId start_idle_app(const char* id) {
+    ensure_memory_loader_registered();
+    AppManifest manifest { id, id, APP_CATEGORY_USER, { APP_LOCATION_MEMORY, reinterpret_cast<void*>(idle_app_main) } };
+    REQUIRE_EQ(app_manager_add(&manifest), ERROR_NONE);
+    AppInstanceId instance_id = 0;
+    REQUIRE_EQ(app_manager_start(id, &instance_id), ERROR_NONE);
+    REQUIRE(wait_for_state(instance_id, APP_INSTANCE_STATE_ACTIVE, 1000));
+    return instance_id;
+}
+
+} // namespace
+
+TEST_CASE("app_stream_read/write move bytes through a ring buffer, respecting capacity") {
+    AppInstanceId producer_id = start_idle_app("test.stream.ringbuffer");
+
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
+    uint8_t storage[4];
+    AppStream stream {};
+    REQUIRE_EQ(app_stream_subscribe(&stream, storage, sizeof(storage), &event_group, producer_id, 5), ERROR_NONE);
+
+    CHECK_EQ(app_stream_write(&stream, "ab", 2), 2u);
+    CHECK_EQ(app_stream_write(&stream, "cdef", 4), 2u); // only 2 bytes of space left
+
+    uint8_t out[8] = {};
+    CHECK_EQ(app_stream_read(&stream, out, sizeof(out)), 4u);
+    CHECK_EQ(std::memcmp(out, "abcd", 4), 0);
+
+    app_stream_unsubscribe(&stream);
+    task_event_group_destruct(&event_group);
+    app_manager_stop(producer_id);
+    app_manager_remove("test.stream.ringbuffer");
+}
+
+TEST_CASE("app_stream_await blocks until data/space is available, and closing forces both bits") {
+    AppInstanceId producer_id = start_idle_app("test.stream.await");
+
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
+    uint8_t storage[2];
+    AppStream stream {};
+    REQUIRE_EQ(app_stream_subscribe(&stream, storage, sizeof(storage), &event_group, producer_id, 5), ERROR_NONE);
+
+    // Nothing written yet, so the readable wait times out.
+    CHECK_EQ(app_stream_await(&stream, APP_FILE_WAIT_READABLE, pdMS_TO_TICKS(50)), ERROR_TIMEOUT);
+
+    app_stream_write(&stream, "x", 1);
+    CHECK_EQ(app_stream_await(&stream, APP_FILE_WAIT_READABLE, pdMS_TO_TICKS(50)), ERROR_NONE);
+
+    app_stream_close(&stream);
+    CHECK_EQ(app_stream_await(&stream, APP_FILE_WAIT_READABLE, pdMS_TO_TICKS(50)), ERROR_NONE);
+    CHECK_EQ(app_stream_await(&stream, APP_FILE_WAIT_WRITABLE, pdMS_TO_TICKS(50)), ERROR_NONE);
+
+    app_stream_unsubscribe(&stream);
+    task_event_group_destruct(&event_group);
+    app_manager_stop(producer_id);
+    app_manager_remove("test.stream.await");
+}
+
+TEST_CASE("app_stream_subscribe over an existing subscription atomically replaces it") {
+    AppInstanceId producer_id = start_idle_app("test.stream.replace");
+
+    TaskEventGroup event_group {};
+    task_event_group_construct(&event_group);
+
+    uint8_t storage_a[4];
+    uint8_t storage_b[4];
+    AppStream stream_a {};
+    REQUIRE_EQ(app_stream_subscribe(&stream_a, storage_a, sizeof(storage_a), &event_group, producer_id, 5), ERROR_NONE);
+
+    AppStream stream_b {};
+    REQUIRE_EQ(app_stream_subscribe(&stream_b, storage_b, sizeof(storage_b), &event_group, producer_id, 5), ERROR_NONE);
+
+    // stream_a was replaced: it's now closed (readable reports ready, and reads 0 bytes / EOF),
+    // even though nobody explicitly unsubscribed it.
+    CHECK_EQ(app_stream_await(&stream_a, APP_FILE_WAIT_READABLE, pdMS_TO_TICKS(50)), ERROR_NONE);
+    CHECK_EQ(app_stream_read(&stream_a, storage_a, sizeof(storage_a)), 0u);
+
+    app_stream_unsubscribe(&stream_a);
+    app_stream_unsubscribe(&stream_b);
+    task_event_group_destruct(&event_group);
+    app_manager_stop(producer_id);
+    app_manager_remove("test.stream.replace");
+}

Tactility/Source/AppStdioWrap.cpp

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: Apache-2.0
+#ifdef ESP_PLATFORM
+
+#include <app/io.h>
+
+#include <sys/types.h>
+
+extern "C" {
+
+ssize_t __wrap_read(int fd, void* buffer, size_t size) {
+    return app_io_read(fd, buffer, size);
+}
+
+ssize_t __wrap_write(int fd, const void* buffer, size_t size) {
+    return app_io_write(fd, buffer, size);
+}
+
+int __wrap_close(int fd) {
+    return app_io_close(fd);
+}
+
+}
+
+#endif // ESP_PLATFORM