Merge pull request #521 from tock/ywf

Implement Yield-WaitFor, add guide doc for YWF, demonstration with temperature

Author: ppannuto

doc/guide.md

@@ -236,7 +236,7 @@ they should have the last argument be a callback function pointer.
 returncode_t libtock_[name]_[desc](<arguments>, libtock_[name]_callback_[desc] cb);
 ```
 
-### Example
+### Example:
 
 
 For example, a library called "sensor" with a sensor read operation should look
@@ -277,23 +277,103 @@ returncode_t libtock_sensor_read(libtock_sensor_callback_reading cb) {
 
 ## Synchronous APIs
 
-Most system call interfaces will want to provide a synchronous API as well.
+Most system call interfaces will want to provide a synchronous API as well. This
+requires another file for syscalls.
+
+All synchronous APIs MUST use the
+[Yield-WaitFor](https://book.tockos.org/trd/trd104-syscalls.html#413-yield-waitfor)
+(`yield_wait_for()`) variant of the yield syscall. This ensures predictable
+behavior for `libtock-sync` users because Yield-WaitFor ensures that no other
+application upcall will run until the synchronous API has finished.
+
+### Synchronous Syscall APIs
+
+| Characteristic   | Value                                                |
+|------------------|------------------------------------------------------|
+| Location         | `libtock-sync/[category]/syscalls`                   |
+| Source File Name | `libtock-sync/[category]/syscalls/[name]_syscalls.c` |
+| Header File Name | `libtock-sync/[category]/syscalls/[name]_syscalls.h` |
+
+### Synchronous Syscall Header File
+
+The `[name]_syscalls.h` must be wrapped in `extern "C" { ... }` if the header
+file is used in a C++ app.
+
+#### Example:
+
+```c
+#pragma once
+
+#include <libtock/tock.h>
+#include <libtock/[category]/syscalls/[name]_syscalls.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// Signatures go here.
+
+#ifdef __cplusplus
+}
+#endif
+```
+
+### Yield-WaitFor
+
+Each supported upcall must have a matching Yield-WaitFor call. This function
+calls `yield_wait_for()` and interprets the `yield_waitfor_return_t` return
+value arguments.
+
+The signature is:
+
+```c
+returncode_t libtocksync_[name]_yield_wait_for(<arguments>);
+```
+
+If only one upcall is supported, the function name must be
+`libtocksync_[name]_yield_wait_for`.
+
+If more than one upcall is supported, the function names must start with
+`libtocksync_[name]_yield_wait_for_` followed by the same description of what
+the upcall is used for from the `libtock` library.
+
+The arguments must be appropriately named pointers to data types returned by the
+upcall, except for any returned ReturnCode. The ReturnCode must be returned from
+the function.
+
+#### Example:
+
+```c
+returncode_t libtocksync_[name]_yield_wait_for(int* value) {
+  yield_waitfor_return_t ret;
+  ret = yield_wait_for(DRIVER_NUM_[NAME], 0);
+  if (ret.data0 != RETURNCODE_SUCCESS) return ret.data0;
+
+  *value = (int) ret.data1;
+  return RETURNCODE_SUCCESS;
+}
+```
+
+### Synchronous Operations
+
+The asynchronous operations should have matching synchronous versions using
+Yield-WaitFor internally.
 
 | Characteristic   | Value                              |
 |------------------|------------------------------------|
 | Location         | `libtock-sync/[category]`          |
 | Source File Name | `libtock-sync/[category]/[name].c` |
 | Header File Name | `libtock-sync/[category]/[name].h` |
 
-### Header Files
+### Synchronous Operation Header Files
 
 The libtock-sync `[name].h` header file must look like:
 
 ```c
 #pragma once
 
+#include "syscalls/temperature_syscalls.h"
 #include <libtock/tock.h>
-#include <libtock/[category]/[name].h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -306,7 +386,7 @@ extern "C" {
 #endif
 ```
 
-### Synchronous APIs
+### Example:
 
 For our sensor example:
 
@@ -337,17 +417,13 @@ operation:
 
 ```c
 returncode_t libtocksync_sensor_read(int* val) {
-  int err;
-  result.fired = false;
+  returncode_t err;
 
-  err = libtock_sensor_read(sensor_cb);
+  err = libtock_sensor_command_read();
   if (err != RETURNCODE_SUCCESS) return err;
 
-  // Wait for the callback.
-  yield_for(&result.fired);
-  if (result.result != RETURNCODE_SUCCESS) return result.result;
-
-  *val = result.val;
-  return RETURNCODE_SUCCESS;
+  // Wait for the operation to finish.
+  err = libtock_temperature_yield_wait_for(val);
+  return err;
 }
 ```

examples/tests/temperature/Makefile

@@ -0,0 +1,11 @@
+# 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 userland master makefile. Contains rules and flags for actually
+# building the application.
+include $(TOCK_USERLAND_BASE_DIR)/AppMakefile.mk

examples/tests/temperature/README.md

@@ -0,0 +1,4 @@
+Simple Temperature Test
+=======================
+
+Uses libtock-sync to read the temperature sensor.

examples/tests/temperature/main.c

@@ -0,0 +1,28 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <libtock-sync/sensors/temperature.h>
+
+int main(void) {
+  returncode_t ret;
+
+  if (!libtock_temperature_exists()) {
+    printf("[Temperature] No temperature sensor found.\n");
+    exit(-1);
+  }
+
+  int temp;
+  ret = libtocksync_temperature_read(&temp);
+  if (ret != RETURNCODE_SUCCESS) {
+    printf("[Temperature] Error reading temperature sensor.\n");
+    printf("[Temperature] %s\n", tock_strrcode(ret));
+    exit(-2);
+  }
+
+  int temp_ones       = temp / 100;
+  int temp_hundredths = temp - (temp_ones * 100);
+  printf("[Temperature] %d.%d deg C\n", temp_ones, temp_hundredths);
+
+  return 0;
+}

libtock-sync/Makefile

@@ -16,6 +16,7 @@ $(LIBNAME)_SRCS  += $(wildcard $($(LIBNAME)_DIR)/kernel/*.c)
 $(LIBNAME)_SRCS  += $(wildcard $($(LIBNAME)_DIR)/net/*.c)
 $(LIBNAME)_SRCS  += $(wildcard $($(LIBNAME)_DIR)/peripherals/*.c)
 $(LIBNAME)_SRCS  += $(wildcard $($(LIBNAME)_DIR)/sensors/*.c)
+$(LIBNAME)_SRCS  += $(wildcard $($(LIBNAME)_DIR)/sensors/syscalls/*.c)
 $(LIBNAME)_SRCS  += $(wildcard $($(LIBNAME)_DIR)/services/*.c)
 $(LIBNAME)_SRCS  += $(wildcard $($(LIBNAME)_DIR)/storage/*.c)
 

libtock-sync/sensors/syscalls/temperature_syscalls.c

@@ -0,0 +1,9 @@
+#include "temperature_syscalls.h"
+
+returncode_t libtocksync_temperature_yield_wait_for(int* temp) {
+  yield_waitfor_return_t ret;
+  ret = yield_wait_for(DRIVER_NUM_TEMPERATURE, 0);
+
+  *temp = (int) ret.data0;
+  return RETURNCODE_SUCCESS;
+}

libtock-sync/sensors/syscalls/temperature_syscalls.h

@@ -0,0 +1,15 @@
+#pragma once
+
+#include <libtock/sensors/syscalls/temperature_syscalls.h>
+#include <libtock/tock.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// Wait for a temperature read to finish.
+returncode_t libtocksync_temperature_yield_wait_for(int* temp);
+
+#ifdef __cplusplus
+}
+#endif

libtock-sync/sensors/temperature.c

@@ -1,31 +1,13 @@
 #include "temperature.h"
 
-struct data {
-  bool fired;
-  int temp;
-  returncode_t result;
-};
-
-static struct data result = { .fired = false };
-
-static void temp_cb(returncode_t ret, int temperature) {
-  result.temp   = temperature;
-  result.fired  = true;
-  result.result = ret;
-}
-
 returncode_t libtocksync_temperature_read(int* temperature) {
   returncode_t err;
-  result.fired = false;
 
-  err = libtock_temperature_read(temp_cb);
+  err = libtock_temperature_command_read();
   if (err != RETURNCODE_SUCCESS) return err;
 
-  // Wait for the callback.
-  yield_for(&result.fired);
-  if (result.result != RETURNCODE_SUCCESS) return result.result;
-
-  *temperature = result.temp;
+  // Wait for the operation to finish.
+  err = libtocksync_temperature_yield_wait_for(temperature);
 
-  return RETURNCODE_SUCCESS;
+  return err;
 }

libtock-sync/sensors/temperature.h

@@ -1,6 +1,6 @@
 #pragma once
 
-#include <libtock/sensors/temperature.h>
+#include "syscalls/temperature_syscalls.h"
 #include <libtock/tock.h>
 
 #ifdef __cplusplus

libtock/tock.c

@@ -184,6 +184,25 @@ int yield_no_wait(void) {
   return (int)result;
 }
 
+yield_waitfor_return_t yield_wait_for(uint32_t driver, uint32_t subscribe) {
+  register uint32_t waitfor __asm__ ("r0") = 2; // yield-waitfor
+  register uint32_t r1 __asm__ ("r1")      = driver;
+  register uint32_t r2 __asm__ ("r2")      = subscribe;
+  register int rv0 __asm__ ("r0");
+  register int rv1 __asm__ ("r1");
+  register int rv2 __asm__ ("r2");
+
+  __asm__ volatile (
+    "svc 0       \n"
+    : "=r" (rv0), "=r" (rv1), "=r" (rv2)
+    : "r" (waitfor), "r" (r1), "r" (r2)
+    : "memory"
+    );
+  yield_waitfor_return_t rv = {rv0, rv1, rv2};
+  return rv;
+}
+
+
 void tock_exit(uint32_t completion_code) {
   register uint32_t r0 __asm__ ("r0") = 0; // Terminate
   register uint32_t r1 __asm__ ("r1") = completion_code;
@@ -400,6 +419,23 @@ int yield_no_wait(void) {
   return (int)result;
 }
 
+yield_waitfor_return_t yield_wait_for(uint32_t driver, uint32_t subscribe) {
+  register uint32_t waitfor __asm__ ("a0") = 2; // yield-waitfor
+  register uint32_t a1 __asm__ ("a1")      = driver;
+  register uint32_t a2 __asm__ ("a2")      = subscribe;
+  register uint32_t a4 __asm__ ("a4")      = 0; // Yield
+  register int rv0 __asm__ ("a0");
+  register int rv1 __asm__ ("a1");
+  register int rv2 __asm__ ("a2");
+  __asm__ volatile (
+    "ecall\n"
+    : "=r" (rv0), "=r" (rv1), "=r" (rv2)
+    : "r" (waitfor), "r" (a1), "r" (a2), "r" (a4)
+    : "memory");
+  yield_waitfor_return_t rv = {rv0, rv1, rv2};
+  return rv;
+}
+
 
 void tock_restart(uint32_t completion_code) {
   register uint32_t a0  __asm__ ("a0") = 1; // exit-restart