tests: app_loader: add uninstall test app + matching syscalls and wrappers

Author: viswajith-g

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

@@ -0,0 +1,10 @@
+# Makefile for user application
+
+# Specify this directory relative to the current application.
+TOCK_USERLAND_BASE_DIR = ../../../..
+
+# Which files to compile.
+C_SRCS := $(wildcard *.c)
+
+# Include app loading support rules. Rules to generate app binary images.
+include $(TOCK_USERLAND_BASE_DIR)/AppMakefile.mk

examples/tests/app_loader/button-press-uninstall/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.

examples/tests/app_loader/button-press-uninstall/main.c

@@ -0,0 +1,95 @@
+#include <math.h>
+#include <stdio.h>
+#include <string.h>
+
+#include <libtock-sync/services/alarm.h>
+#include <libtock/interface/button.h>
+#include <libtock/kernel/app_loader.h>
+#include <libtock/tock.h>
+
+#include <inttypes.h>
+
+/******************************************************************************************************
+* Short ID and version of app that has to be uninstalled (Blink in this case)
+******************************************************************************************************/
+const uint32_t short_id = 4246331976;
+const uint32_t version  = 0;
+
+/******************************************************************************************************
+* Callback Tracking Flags
+******************************************************************************************************/
+static bool uninstall_done = false;   // to check if setup is done
+static bool app_uninstall  = false;   // to track if app has to be uninstalled
+
+/******************************************************************************************************
+* Callback functions
+*
+* Set button callback to initiate the uninstall on pressing buttons
+******************************************************************************************************/
+
+static void app_uninstall_done_callback(__attribute__((unused)) int   arg0,
+                                        __attribute__((unused)) int   arg1,
+                                        __attribute__((unused)) int   arg2,
+                                        __attribute__((unused)) void* ud) {
+
+  if (arg0 != RETURNCODE_SUCCESS) {
+    printf("[Error] Uninstall failed: %d.\n", arg0);
+  } else {
+    printf("[Success] Uninstalled app successfully.\n");
+  }
+  uninstall_done = true;
+}
+
+// Callback for button presses.
+static void button_callback(__attribute__ ((unused)) returncode_t retval, int btn_num, __attribute__ (
+                              (unused)) bool pressed) {
+  // Callback for button presses.
+  if (btn_num == 0) {
+    app_uninstall = true;
+  } else {
+    printf("[App Uninstaller] Invalid button selected. Unable to uninstall!\n");
+  }
+}
+
+
+/******************************************************************************************************
+* Main
+******************************************************************************************************/
+
+int main(void) {
+  printf("[Log] Simple test app to uninstall an app during runtime.\n");
+
+  // check if app loader driver exists
+  if (!libtock_app_loader_exists()) {
+    printf("No App Loader driver!\n");
+    return -1;
+  }
+
+  int count;
+  int err = libtock_button_count(&count);
+  // Ensure there is a button to use.
+  if (err < 0) return err;
+  printf("[Log] There are %d buttons on this board.\n", count);
+
+  // Enable interrupts on each button.
+  for (int i = 0; i < count; i++) {
+    libtock_button_notify_on_press(i, button_callback);
+  }
+
+  printf("[Log] Waiting for a button press.\n");
+
+  while (1) {
+    if (app_uninstall) {
+      printf("Uninstalling app with Short ID: %" PRIu32 " and version %" PRIu32 "\n", short_id, version);
+      int ret = libtock_app_loader_uninstall(short_id, version, app_uninstall_done_callback);
+      if (ret != RETURNCODE_SUCCESS) {
+        printf("[Error] Uninstall Failed: %d.\n", ret);
+        tock_exit(ret);
+      }
+      yield_for(&uninstall_done);
+      uninstall_done = false;
+      app_uninstall  = false;
+    }
+    yield();
+  }
+}

libtock/kernel/app_loader.c

@@ -143,3 +143,20 @@ returncode_t libtock_app_loader_abort(subscribe_upcall cb) {
 
   return libtock_app_loader_command_abort();
 }
+
+/******************************************************************************************************
+* Function to uninstall an existing application
+*
+* Takes the short id and version of the app and the callback function as arguments
+******************************************************************************************************/
+
+returncode_t libtock_app_loader_uninstall(uint32_t app_short_id, uint32_t app_version, subscribe_upcall cb) {
+  // set up the uninstall done callback
+  int err = libtock_app_loader_set_uninstall_upcall(cb, NULL);
+  if (err != 0) {
+    printf("[Error] Failed to set setup done callback: %d\n", err);
+    return err;
+  }
+
+  return libtock_app_loader_command_uninstall(app_short_id, app_version);
+}

libtock/kernel/app_loader.h

@@ -18,6 +18,8 @@ returncode_t libtock_app_loader_load(subscribe_upcall cb);
 
 returncode_t libtock_app_loader_abort(subscribe_upcall cb);
 
+returncode_t libtock_app_loader_uninstall(uint32_t app_short_id, uint32_t app_version, subscribe_upcall cb);
+
 
 #ifdef __cplusplus
 }

libtock/kernel/syscalls/app_loader_syscalls.c

@@ -29,6 +29,11 @@ returncode_t libtock_app_loader_set_abort_upcall(subscribe_upcall cb, void* user
   return tock_subscribe_return_to_returncode(sval);
 }
 
+returncode_t libtock_app_loader_set_uninstall_upcall(subscribe_upcall cb, void* userdata) {
+  subscribe_return_t sval = subscribe(DRIVER_NUM_APP_LOADER, 5, cb, userdata);
+  return tock_subscribe_return_to_returncode(sval);
+}
+
 returncode_t libtock_app_loader_write_buffer(uint8_t* buffer, uint32_t len) {
   allow_ro_return_t aval = allow_readonly(DRIVER_NUM_APP_LOADER, 0, (void*) buffer, len);
   return tock_allow_ro_return_to_returncode(aval);
@@ -57,4 +62,9 @@ returncode_t libtock_app_loader_command_load(void) {
 returncode_t libtock_app_loader_command_abort(void) {
   syscall_return_t res = command(DRIVER_NUM_APP_LOADER, 5, 0, 0);
   return tock_command_return_novalue_to_returncode(res);
+}
+
+returncode_t libtock_app_loader_command_uninstall(uint32_t app_short_id, uint32_t app_version) {
+  syscall_return_t res = command(DRIVER_NUM_APP_LOADER, 6, app_short_id, app_version);
+  return tock_command_return_novalue_to_returncode(res);
 }

libtock/kernel/syscalls/app_loader_syscalls.h

@@ -15,26 +15,12 @@ extern "C"
  */
 bool libtock_app_loader_exists(void);
 
-/*
- * Function to setup the callback from capsule.
- * This function takes in the function that will be executed
- * when the callback is triggered.
- */
-returncode_t libtock_app_loader_set_setup_upcall(subscribe_upcall cb, void* userdata);
-
 /*
  * Command to request the kernel to set up for a new app.
  * This functions takes the size of the new app as the argument.
  */
 returncode_t libtock_app_loader_command_setup(uint32_t app_length);
 
-/*
- * Function to setup the callback from capsule.
- * This function takes in the function that will be executed
- * when the callback is triggered.
- */
-returncode_t libtock_app_loader_set_write_upcall(subscribe_upcall cb, void* userdata);
-
 /*
  * Function to set up a shared buffer with the capsule.
  * This buffer is used to write data to the flash.
@@ -51,13 +37,6 @@ returncode_t libtock_app_loader_write_buffer(uint8_t* buffer, uint32_t len);
  */
 returncode_t libtock_app_loader_command_write(uint32_t flash_offset, uint32_t write_length);
 
-/*
- * Function to setup the callback from capsule.
- * This function takes in the function that will be executed
- * when the callback is triggered.
- */
-returncode_t libtock_app_loader_set_finalize_upcall(subscribe_upcall cb, void* userdata);
-
 /*
  * Signal to kernel we are done writing a new process binary.
  */
@@ -69,23 +48,26 @@ returncode_t libtock_app_loader_command_finalize(void);
 returncode_t libtock_app_loader_command_load(void);
 
 /*
- * Function to setup the callback from capsule.
- * This function takes in the function that will be executed
- * when the callback is triggered.
+ * Command to request the kernel to abort setup/writing process.
  */
-returncode_t libtock_app_loader_set_load_upcall(subscribe_upcall cb, void* userdata);
+returncode_t libtock_app_loader_command_abort(void);
 
 /*
- * Command to request the kernel to abort setup/writing process.
+ * Command to request the kernel to uninstall an application.
  */
-returncode_t libtock_app_loader_command_abort(void);
+returncode_t libtock_app_loader_command_uninstall(uint32_t app_short_id, uint32_t app_version);
 
 /*
- * Function to setup the callback from capsule.
+ * Functions to setup the callback from capsule.
  * This function takes in the function that will be executed
  * when the callback is triggered.
  */
+returncode_t libtock_app_loader_set_setup_upcall(subscribe_upcall cb, void* userdata);
+returncode_t libtock_app_loader_set_write_upcall(subscribe_upcall cb, void* userdata);
+returncode_t libtock_app_loader_set_finalize_upcall(subscribe_upcall cb, void* userdata);
+returncode_t libtock_app_loader_set_load_upcall(subscribe_upcall cb, void* userdata);
 returncode_t libtock_app_loader_set_abort_upcall(subscribe_upcall cb, void* userdata);
+returncode_t libtock_app_loader_set_uninstall_upcall(subscribe_upcall cb, void* userdata);