Version independent external apps (standalone apps) (#2145)

This pull requests adds a new type of external app to the firmware: The standalone app.

Pros:

Will work after an upgrade.
Size of image is only limited by shared heap size of M0 (application) (64kb total).
Cons:

No full access to all functions in the main firmware. One well defined (and versioned) API handles all communication.
The Pacman app was converted to be the first the the new kind.

firmware/application/CMakeLists.txt

@@ -325,6 +325,7 @@ set(CPPSRC
 	# apps/ui_spectrum_painter.cpp
 	apps/ui_ss_viewer.cpp
 	apps/ui_sstvtx.cpp
+	apps/ui_standalone_view.cpp
 	apps/ui_subghzd.cpp
 	# apps/ui_test.cpp
 	apps/ui_text_editor.cpp

firmware/application/apps/ui_standalone_view.cpp

@@ -0,0 +1,82 @@
+/*
+ * Copyright (C) 2024 Bernd Herzog
+ *
+ * This file is part of PortaPack.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; see the file COPYING.  If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#include "ui_standalone_view.hpp"
+#include "irq_controls.hpp"
+
+namespace ui {
+
+void create_thread(int32_t (*fn)(void*), void* arg, size_t stack_size, int priority) {
+    // TODO: collect memory on terminate, once this is used
+    chThdCreateFromHeap(NULL, stack_size, priority, fn, arg);
+}
+
+void fill_rectangle(int x, int y, int width, int height, uint16_t color) {
+    ui::Painter painter;
+    painter.fill_rectangle({x, y, width, height}, ui::Color(color));
+}
+
+void* alloc(size_t size) {
+    void* p = chHeapAlloc(0x0, size);
+    if (p == nullptr)
+        chDbgPanic("Out of Memory");
+    return p;
+}
+
+uint64_t get_switches_state_ulong() {
+    return get_switches_state().to_ulong();
+}
+
+standalone_application_api_t api = {
+    /* .malloc = */ &alloc,
+    /* .calloc = */ &calloc,
+    /* .realloc = */ &realloc,
+    /* .free = */ &chHeapFree,
+    /* .create_thread = */ &create_thread,
+    /* .fill_rectangle = */ &fill_rectangle,
+    /* .swizzled_switches = */ &swizzled_switches,
+    /* .get_switches_state = */ &get_switches_state_ulong,
+};
+
+StandaloneView::StandaloneView(NavigationView& nav, std::unique_ptr<uint8_t[]> app_image)
+    : nav_(nav), _app_image(std::move(app_image)) {
+    get_application_information()->initialize(api);
+    add_children({&dummy});
+}
+
+void StandaloneView::focus() {
+    dummy.focus();
+}
+
+void StandaloneView::paint(Painter& painter) {
+    (void)painter;
+}
+
+void StandaloneView::frame_sync() {
+    // skip first refresh
+    if (!initialized) {
+        initialized = true;
+    } else {
+        get_application_information()->on_event(1);
+    }
+}
+
+}  // namespace ui

firmware/application/apps/ui_standalone_view.hpp

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2023 Bernd Herzog
+ * Copyright (C) 2024 Bernd Herzog
  *
  * This file is part of PortaPack.
  *
@@ -19,22 +19,24 @@
  * Boston, MA 02110-1301, USA.
  */
 
-#ifndef __UI_PACMAN_H__
-#define __UI_PACMAN_H__
+#ifndef __UI_STANDALONE_VIEW_H__
+#define __UI_STANDALONE_VIEW_H__
 
 #include "ui_navigation.hpp"
 #include "event_m0.hpp"
 #include "message.hpp"
+#include "standalone_app.hpp"
 
-namespace ui::external_app::pacman {
+namespace ui {
 
-class PacmanView : public View {
+class StandaloneView : public View {
    public:
-    PacmanView(NavigationView& nav);
+    StandaloneView(NavigationView& nav, std::unique_ptr<uint8_t[]> app_image);
+    virtual ~StandaloneView() override { get_application_information()->shutdown(); }
 
     void focus() override;
 
-    std::string title() const override { return "Pac-Man"; };
+    std::string title() const override { return (const char*)get_application_information()->app_name; };
 
     void paint(Painter& painter) override;
     void frame_sync();
@@ -42,6 +44,10 @@ class PacmanView : public View {
    private:
     bool initialized = false;
     NavigationView& nav_;
+    std::unique_ptr<uint8_t[]> _app_image;
+    standalone_application_information_t* get_application_information() const {
+        return reinterpret_cast<standalone_application_information_t*>(_app_image.get());
+    }
 
     Button dummy{
         {240, 0, 0, 0},
@@ -54,6 +60,6 @@ class PacmanView : public View {
         }};
 };
 
-}  // namespace ui::external_app::pacman
+}  // namespace ui
 
-#endif /*__UI_PACMAN_H__*/
+#endif /*__UI_STANDALONE_VIEW_H__*/

firmware/application/external/external.cmake

@@ -1,9 +1,5 @@
 set(EXTCPPSRC
 
-	#pacman
-	external/pacman/main.cpp
-	external/pacman/ui_pacman.cpp
-
 	#tetris
 	external/tetris/main.cpp
 	external/tetris/ui_tetris.cpp
@@ -87,7 +83,6 @@ set(EXTCPPSRC
 )
 
 set(EXTAPPLIST
-	pacman
 	afsk_rx
 	calculator
 	font_viewer

firmware/application/external/external.ld

@@ -23,7 +23,6 @@ MEMORY
      * Also need to consider processor memory map - reading 0xADxxxxxx generates a fault which may be better than unexpected behavior.
      * External app address ranges below must match those in python file "external_app_info.py".
      */
-    ram_external_app_pacman     (rwx) : org = 0xADB00000, len = 32k
     ram_external_app_afsk_rx    (rwx) : org = 0xADB10000, len = 32k
     ram_external_app_calculator (rwx) : org = 0xADB20000, len = 32k
     ram_external_app_font_viewer(rwx) : org = 0xADB30000, len = 32k
@@ -47,12 +46,6 @@ MEMORY
 
 SECTIONS
 {
-    .external_app_pacman : ALIGN(4) SUBALIGN(4)
-    {
-        KEEP(*(.external_app.app_pacman.application_information));
-        *(*ui*external_app*pacman*);
-    } > ram_external_app_pacman
-
     .external_app_afsk_rx : ALIGN(4) SUBALIGN(4)
     {
         KEEP(*(.external_app.app_afsk_rx.application_information));

firmware/application/external/pacman/DrawIndexedMap.h

@@ -1,66 +0,0 @@
-/******************************************************************************/
-/*                                                                            */
-/*  PACMAN GAME FOR ARDUINO DUE                                               */
-/*                                                                            */
-/******************************************************************************/
-/*  Copyright (c) 2014  Dr. NCX (mirracle.mxx@gmail.com)                      */
-/*                                                                            */
-/* THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL              */
-/* WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED              */
-/* WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR    */
-/* BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES      */
-/* OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,     */
-/* WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,     */
-/* ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS        */
-/* SOFTWARE.                                                                  */
-/*                                                                            */
-/*  MIT license, all text above must be included in any redistribution.       */
-
-// #include "ili9328.h"
-
-typedef uint16_t ushort;
-
-#define C16(_rr, _gg, _bb) ((ushort)(((_rr & 0xF8) << 8) | ((_gg & 0xFC) << 3) | ((_bb & 0xF8) >> 3)))
-
-uint16_t _paletteW[] =
-    {
-        C16(0, 0, 0),
-        C16(255, 0, 0),     // 1 red
-        C16(222, 151, 81),  // 2 brown
-        C16(255, 0, 255),   // 3 pink
-
-        C16(0, 0, 0),
-        C16(0, 255, 255),   // 5 cyan
-        C16(71, 84, 255),   // 6 mid blue
-        C16(255, 184, 81),  // 7 lt brown
-
-        C16(0, 0, 0),
-        C16(255, 255, 0),  // 9 yellow
-        C16(0, 0, 0),
-        C16(33, 33, 255),  // 11 blue
-
-        C16(0, 255, 0),      // 12 green
-        C16(71, 84, 174),    // 13 aqua
-        C16(255, 184, 174),  // 14 lt pink
-        C16(222, 222, 255),  // 15 whiteish
-};
-
-void drawIndexedmap(uint8_t* indexmap, int16_t x, uint16_t y) {
-    ui::Painter painter;
-
-    byte i = 0;
-    word color = (word)_paletteW[indexmap[0]];
-    for (byte tmpY = 0; tmpY < 8; tmpY++) {
-        byte width = 1;
-        for (byte tmpX = 0; tmpX < 8; tmpX++) {
-            word next_color = (word)_paletteW[indexmap[++i]];
-            if ((color != next_color && width >= 1) || tmpX == 7) {
-                painter.draw_hline({x + tmpX - width + 1, y + tmpY}, width, ui::Color(color));
-
-                color = next_color;
-                width = 0;
-            }
-            width++;
-        }
-    }
-}

firmware/application/external/pacman/main.cpp

@@ -1,82 +0,0 @@
-/*
- * Copyright (C) 2023 Bernd Herzog
- *
- * This file is part of PortaPack.
- *
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2, or (at your option)
- * any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; see the file COPYING.  If not, write to
- * the Free Software Foundation, Inc., 51 Franklin Street,
- * Boston, MA 02110-1301, USA.
- */
-
-#include "ui.hpp"
-#include "ui_pacman.hpp"
-#include "ui_navigation.hpp"
-#include "external_app.hpp"
-
-namespace ui::external_app::pacman {
-void initialize_app(ui::NavigationView& nav) {
-    nav.push<PacmanView>();
-}
-}  // namespace ui::external_app::pacman
-
-extern "C" {
-
-__attribute__((section(".external_app.app_pacman.application_information"), used)) application_information_t _application_information_pacman = {
-    /*.memory_location = */ (uint8_t*)0x00000000,  // will be filled at compile time
-    /*.externalAppEntry = */ ui::external_app::pacman::initialize_app,
-    /*.header_version = */ CURRENT_HEADER_VERSION,
-    /*.app_version = */ VERSION_MD5,
-
-    /*.app_name = */ "Pac-Man",
-    /*.bitmap_data = */ {
-        0x00,
-        0x00,
-        0x00,
-        0x00,
-        0xC0,
-        0x07,
-        0xE0,
-        0x0F,
-        0xF0,
-        0x1F,
-        0xF8,
-        0x07,
-        0xF8,
-        0x01,
-        0x78,
-        0x00,
-        0xF8,
-        0x01,
-        0xF8,
-        0x07,
-        0xF0,
-        0x1F,
-        0xE0,
-        0x0F,
-        0xC0,
-        0x07,
-        0x00,
-        0x00,
-        0x00,
-        0x00,
-        0x00,
-        0x00,
-    },
-    /*.icon_color = */ ui::Color::yellow().v,
-    /*.menu_location = */ app_location_t::UTILITIES,
-
-    /*.m4_app_tag = portapack::spi_flash::image_tag_none */ {0, 0, 0, 0},
-    /*.m4_app_offset = */ 0x00000000,  // will be filled at compile time
-};
-}

firmware/application/external/pacman/ui_pacman.cpp

@@ -1,65 +0,0 @@
-#include "ui_pacman.hpp"
-#include "irq_controls.hpp"
-
-namespace ui::external_app::pacman {
-
-#pragma GCC diagnostic push
-// external code, so ignore warnings
-#pragma GCC diagnostic ignored "-Wunused-variable"
-#pragma GCC diagnostic ignored "-Wunused-parameter"
-#pragma GCC diagnostic ignored "-Wunused-but-set-variable"
-#pragma GCC diagnostic ignored "-Wreturn-type"
-#pragma GCC diagnostic ignored "-Weffc++"
-#include "playfield.hpp"
-#pragma GCC diagnostic pop
-
-PacmanView::PacmanView(NavigationView& nav)
-    : nav_(nav) {
-    add_children({&dummy});
-}
-
-void PacmanView::focus() {
-    dummy.focus();
-}
-
-void PacmanView::paint(Painter& painter) {
-    (void)painter;
-    static Playfield _game;
-    static bool wait_for_button_release{false};
-
-    if (!initialized) {
-        initialized = true;
-        _game.Init();
-    }
-
-    auto switches_raw = swizzled_switches() & ((1 << (int)Switch::Right) | (1 << (int)Switch::Left) | (1 << (int)Switch::Down) | (1 << (int)Switch::Up) | (1 << (int)Switch::Sel) | (1 << (int)Switch::Dfu));
-    auto switches_debounced = get_switches_state().to_ulong();
-
-    // For the Select (Start/Pause) button, wait for release to avoid repeat
-    uint8_t buttons_to_wait_for = (1 << (int)Switch::Sel);
-    if (wait_for_button_release) {
-        if ((switches_debounced & buttons_to_wait_for) == 0)
-            wait_for_button_release = false;
-        switches_debounced &= ~buttons_to_wait_for;
-    } else {
-        if (switches_debounced & buttons_to_wait_for)
-            wait_for_button_release = true;
-    }
-
-    // For the directional buttons, use the raw inputs for fastest response time
-    but_RIGHT = (switches_raw & (1 << (int)Switch::Right)) != 0;
-    but_LEFT = (switches_raw & (1 << (int)Switch::Left)) != 0;
-    but_DOWN = (switches_raw & (1 << (int)Switch::Down)) != 0;
-    but_UP = (switches_raw & (1 << (int)Switch::Up)) != 0;
-
-    // For the pause button, use the debounced input to avoid glitches, and OR in the value to make sure that we don't clear it before it's seen
-    but_A |= (switches_debounced & (1 << (int)Switch::Sel)) != 0;
-
-    _game.Step();
-}
-
-void PacmanView::frame_sync() {
-    set_dirty();
-}
-
-}  // namespace ui::external_app::pacman

firmware/application/ui_external_items_menu_loader.cpp

@@ -2,6 +2,7 @@
 
 #include "sd_card.hpp"
 #include "file_path.hpp"
+#include "ui_standalone_view.hpp"
 
 namespace ui {
 
@@ -10,8 +11,10 @@ namespace ui {
 // iterates over all ppma-s, and if it is runnable on the current system, it'll call the callback, and pass info.
 /* static */ void ExternalItemsMenuLoader::load_all_external_items_callback(std::function<void(AppInfoConsole&)> callback) {
     if (!callback) return;
+
     if (sd_card::status() != sd_card::Status::Mounted)
         return;
+
     for (const auto& entry : std::filesystem::directory_iterator(apps_dir, u"*.ppma")) {
         auto filePath = apps_dir / entry.path();
         File app;
@@ -43,6 +46,37 @@ namespace ui {
             .appLocation = application_information.menu_location};
         callback(info);
     }
+
+    for (const auto& entry : std::filesystem::directory_iterator(apps_dir, u"*.ppmp")) {
+        auto filePath = apps_dir / entry.path();
+        File app;
+
+        auto openError = app.open(filePath);
+        if (openError)
+            continue;
+
+        standalone_application_information_t application_information = {};
+
+        auto readResult = app.read(&application_information, sizeof(standalone_application_information_t));
+        if (!readResult)
+            continue;
+
+        if (application_information.header_version < CURRENT_STANDALONE_APPLICATION_API_VERSION)
+            continue;
+
+        // here the app is startable and good.
+        std::string appshortname = filePath.filename().string();
+        if (appshortname.size() >= 5 && appshortname.substr(appshortname.size() - 5) == ".ppmp") {
+            // Remove the ".ppmp" suffix
+            appshortname = appshortname.substr(0, appshortname.size() - 5);
+        }
+        AppInfoConsole info{
+            .appCallName = appshortname.c_str(),
+            .appFriendlyName = reinterpret_cast<char*>(&application_information.app_name[0]),
+            .appLocation = application_information.menu_location};
+
+        callback(info);
+    }
 }
 
 /* static */ std::vector<GridItem> ExternalItemsMenuLoader::load_external_items(app_location_t app_location, NavigationView& nav) {
@@ -103,6 +137,44 @@ namespace ui {
         external_apps.push_back(gridItem);
     }
 
+    for (const auto& entry : std::filesystem::directory_iterator(apps_dir, u"*.ppmp")) {
+        auto filePath = apps_dir / entry.path();
+        File app;
+
+        auto openError = app.open(filePath);
+        if (openError)
+            continue;
+
+        standalone_application_information_t application_information = {};
+
+        auto readResult = app.read(&application_information, sizeof(standalone_application_information_t));
+        if (!readResult)
+            continue;
+
+        if (application_information.menu_location != app_location)
+            continue;
+
+        if (application_information.header_version > CURRENT_STANDALONE_APPLICATION_API_VERSION)
+            continue;
+
+        GridItem gridItem = {};
+        gridItem.text = reinterpret_cast<char*>(&application_information.app_name[0]);
+
+        gridItem.color = Color((uint16_t)application_information.icon_color);
+
+        auto dyn_bmp = DynamicBitmap<16, 16>{application_information.bitmap_data};
+        gridItem.bitmap = dyn_bmp.bitmap();
+        bitmaps.push_back(std::move(dyn_bmp));
+
+        gridItem.on_select = [&nav, app_location, filePath]() {
+            if (!run_standalone_app(nav, filePath)) {
+                nav.display_modal("Error", "The .ppmp file in your " + apps_dir.string() + "\nfolder can't be read. Please\nupdate your SD Card content.");
+            }
+        };
+
+        external_apps.push_back(gridItem);
+    }
+
     return external_apps;
 }
 
@@ -187,4 +259,39 @@ namespace ui {
     return true;
 }
 
+/* static */ bool ExternalItemsMenuLoader::run_standalone_app(ui::NavigationView& nav, std::filesystem::path filePath) {
+    File app;
+
+    auto openError = app.open(filePath);
+    if (openError)
+        return false;
+
+    auto app_image = std::make_unique<uint8_t[]>(app.size());
+
+    // read file in 512 byte chunks
+    for (size_t file_read_index = 0; file_read_index < app.size(); file_read_index += std::filesystem::max_file_block_size) {
+        auto bytes_to_read = std::filesystem::max_file_block_size;
+        if (file_read_index + std::filesystem::max_file_block_size > app.size())
+            bytes_to_read = app.size() - file_read_index;
+
+        auto readResult = app.read(&app_image[file_read_index], bytes_to_read);
+        if (!readResult)
+            return false;
+
+        if (readResult.value() < std::filesystem::max_file_block_size)
+            break;
+    }
+
+    for (size_t file_read_index = 0; file_read_index < app.size() / 4; file_read_index++) {
+        uint32_t* ptr = reinterpret_cast<uint32_t*>(&app_image[file_read_index * 4]);
+
+        if (*ptr >= 0xADB10000 && *ptr < (0xADB10000 + 64 * 1024)) {
+            *ptr = *ptr - 0xADB10000 + (uint32_t)app_image.get();
+        }
+    }
+
+    nav.push<StandaloneView>(std::move(app_image));
+    return true;
+}
+
 }  // namespace ui

firmware/application/ui_external_items_menu_loader.hpp

@@ -26,6 +26,7 @@
 #include "ui.hpp"
 #include "ui_navigation.hpp"
 #include "external_app.hpp"
+#include "standalone_app.hpp"
 
 #include "file.hpp"
 
@@ -57,6 +58,7 @@ class ExternalItemsMenuLoader {
     static std::vector<GridItem> load_external_items(app_location_t, NavigationView&);
     ExternalItemsMenuLoader() = delete;
     static bool run_external_app(ui::NavigationView&, std::filesystem::path);
+    static bool run_standalone_app(ui::NavigationView&, std::filesystem::path);
     static void load_all_external_items_callback(std::function<void(AppInfoConsole&)> callback);
 
    private: