Dynamic App Loader Helper

Helpers.mk

@@ -32,6 +32,13 @@ check_no_spaces = \
     $(if $(findstring $(strip $($(strip $1))),$($(strip $1))),,$(error Error: Space in variable $(strip $1))) \
     $(if $(word 2,$($(strip $1))),$(error Error: Multiple entries in variable $(strip $1)),)
 
+# Reject directory paths with trailing slashes.
+#
+# Params:
+#   1. Variable name holding path to test.
+reject_trailing_slash = \
+    $(if $(filter $(dir $1),$1),$(error Error: Trailing slash in path "$1"))
+
 # Check for a ~/ at the beginning of a path variable (TOCK_USERLAND_BASE_DIR).
 # Make will not properly expand this.
 ifdef TOCK_USERLAND_BASE_DIR

examples/tests/app_loader/abort-test/.gitignore

@@ -0,0 +1 @@
+loadable_binaries.h

examples/tests/app_loader/abort-test/Makefile

@@ -0,0 +1,14 @@
+# Makefile for user application
+
+# Specify this directory relative to the current application.
+TOCK_USERLAND_BASE_DIR = ../../../..
+
+# Which files to compile.
+C_SRCS := $(wildcard *.c)
+
+# List of apps to generate embed rules for
+APPS_TO_EMBED := \
+  $(TOCK_USERLAND_BASE_DIR)/examples/tests/adc/adc
+
+# Include app loading support rules. Rules to generate app binary images.
+include ../support/CommonAppMake.mk

examples/tests/app_loader/abort-test/README.md

@@ -0,0 +1,9 @@
+# Dynamic App Loader Abort Test (Helper App)
+============================================
+This app showcases the ability of the `abort` functionality of 
+the Dynamic Process Loader.
+
+When the app boots, it tries to load the `adc` app, aborts midway
+and logs the result. Ideally, we should see:
+`[Success] Abort Successful.`, and the `abort-test` app should 
+terminate.

examples/tests/app_loader/abort-test/main.c

@@ -0,0 +1,125 @@
+#include <math.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <libtock-sync/interface/console.h>
+#include <libtock-sync/services/alarm.h>
+#include <libtock/kernel/app_loader.h>
+#include <libtock/tock.h>
+
+#include "loadable_binaries.h"
+
+/******************************************************************************************************
+* Callback Tracking Flags
+******************************************************************************************************/
+static bool setup_done     = false;     // to check if setup is done
+static bool abort_done     = false;     // to check if write abort was successful
+volatile bool abort_flag   = false;     // track if abort request was sent
+uint32_t write_buffer_size = 4096;
+
+/******************************************************************************************************
+* Function Prototypes
+******************************************************************************************************/
+void abort_test(void);
+
+/******************************************************************************************************
+ * Callback functions
+ *
+ * 1. Set callback to initiate the dynamic app load process
+ * 2. Set callback to call `abort()` with a timer
+ *******************************************************************************************************/
+
+static void app_setup_done_callback(__attribute__((unused)) int   arg0,
+                                    __attribute__((unused)) int   arg1,
+                                    __attribute__((unused)) int   arg2,
+                                    __attribute__((unused)) void* ud) {
+  setup_done = true;
+}
+
+static void app_abort_done_callback(__attribute__((unused)) int   arg0,
+                                    __attribute__((unused)) int   arg1,
+                                    __attribute__((unused)) int   arg2,
+                                    __attribute__((unused)) void* ud) {
+  abort_done = true;
+}
+
+static void abort_alarm_cb(__attribute__ ((unused)) uint32_t now,
+                           __attribute__ ((unused)) uint32_t scheduled,
+                           __attribute__ ((unused)) void*    opaque) {
+  printf("[Timer] Triggering abort now.\n");
+  abort_flag = true;
+  int ret = libtock_app_loader_abort(app_abort_done_callback);
+  if (ret != RETURNCODE_SUCCESS) {
+    printf("[Error] Abort Failed: %d.\n", ret);
+  }
+
+  // wait on abort done callback
+  yield_for(&abort_done);
+  abort_done = false;
+  printf("[Success] Abort Successful.\n");
+}
+
+/******************************************************************************************************
+* Function to test the abort functionality of Tock's dynamic app loading feature set
+*
+* Takes callback function as argument
+******************************************************************************************************/
+
+void abort_test(void) {
+
+  libtock_alarm_t abort_alarm;
+
+  unsigned char* app_data = (uint8_t*)(uintptr_t)binaries[0];
+  size_t app_size         = binary_sizes[0];
+  size_t binary_size      = actual_sizes[0];
+
+  int ret = libtock_app_loader_setup(app_size, app_setup_done_callback);
+  if (ret != RETURNCODE_SUCCESS) {
+    printf("[Error] Setup Failed: %d.\n", ret);
+    tock_exit(ret);
+  }
+
+  // wait on setup done callback
+  yield_for(&setup_done);
+  setup_done = false;
+
+  libtock_alarm_in_ms(150, abort_alarm_cb, NULL, &abort_alarm);
+
+  size_t offset = 0;
+  while (offset < binary_size) {
+    if (abort_flag) break;
+    size_t chunk_len = (binary_size - offset > write_buffer_size)
+                        ? write_buffer_size
+                        : binary_size - offset;
+
+    int ret1 = libtock_app_loader_write(offset, &app_data[offset], chunk_len);
+    if (ret1 != RETURNCODE_SUCCESS) {
+      printf("[Error] Chunk write failed at offset %zu\n", offset);
+      break;
+    }
+    offset += chunk_len;
+  }
+}
+
+/******************************************************************************************************
+* Main
+******************************************************************************************************/
+
+int main(void) {
+  printf("[Log] Simple test app to test abort functionality of dynamic process loading.\n");
+
+  // check if app loader driver exists
+  if (!libtock_app_loader_exists()) {
+    printf("No App Loader driver!\n");
+    return -1;
+  }
+
+  libtocksync_alarm_delay_ms(5000);
+
+  printf("[Log] Initiating Abort Test.\n");
+
+  abort_test();
+
+  printf("[Log] Exiting Abort Test.\n");
+  return 0;
+}

examples/tests/app_loader/button-press-loading/.gitignore

@@ -0,0 +1 @@
+loadable_binaries.h

examples/tests/app_loader/button-press-loading/Makefile

@@ -0,0 +1,15 @@
+# Makefile for user application
+
+# Specify this directory relative to the current application.
+TOCK_USERLAND_BASE_DIR = ../../../..
+
+# Which files to compile.
+C_SRCS := $(wildcard *.c)
+
+# List of apps to generate embed rules for
+APPS_TO_EMBED = \
+  $(TOCK_USERLAND_BASE_DIR)/examples/blink \
+  $(TOCK_USERLAND_BASE_DIR)/examples/tests/adc/adc
+
+# Include app loading support rules. Rules to generate app binary images.
+include ../support/CommonAppMake.mk

examples/tests/app_loader/button-press-loading/README.md

@@ -0,0 +1,47 @@
+# Dynamic App Loader (Helper App)
+=================================
+
+This app waits upon the user to press one of two buttons on the device (if supported).
+
+When Button 1 (Default user button on boards) is pressed, the app tried to load in the 
+`blink` app.
+
+When Button 2 is pressed, the app tries to load in the `adc` app.
+
+There are three stages to this:
+
+1. Setup Phase
+2. Flash Phase
+3. Load Phase
+
+#### Setup Phase
+During the setup phase, the application passes the size of the new app `(blink)/(adc)`'s 
+binary to the app_loader capsule. 
+
+The capsule returns with either a success or failure. 
+
+On success, the app requests the app_loader capsule to flash the `blink/adc` app.
+
+On Failure, the app exits logs the reason for failure and exits.
+
+#### Flash Phase
+The app sends the binary of the `blink/adc` app 512 bytes (this is the size of the shared 
+buffer between the app and the capsule) at a time along with the offset.
+
+The capsule checks that these values do not violate the bounds dictated by the kernel 
+and then requests the kernel to flash the app. 
+
+The kernel performs more stringent checking on the request to ensure that memory access
+violations do not take place, and flashes the app.
+
+The capsule then returns with either a success or failure. 
+
+On success, the app requests the app_loader capsule to load the `blink/adc` app.
+
+On Failure, the app exits logs the reason for failure and exits.
+
+#### Load Phase
+The app requests the capsule to load the new app. There are only two outcomes: 
+
+1. The `blink/adc` app is loaded successfully and functions without requiring a restart.
+2. The load process failed somewhere, and the app is erased.