Merge branch 'lukeshu/stack-sizes'HEADmain

1 files changed, 32 insertions, 6 deletions

diff --git a/libcr/include/libcr/coroutine.h b/libcr/include/libcr/coroutine.h
index 589664f..f0e6e61 100644
--- a/libcr/include/libcr/coroutine.h
+++ b/libcr/include/libcr/coroutine.h
@@ -83,7 +83,15 @@ typedef void (*cr_fn_t)(void *args);
 /* managing coroutines ********************************************************/
 
 /**
- * Call `fn(args)` in a new coroutine with stack size `stack_size`.
+ * Call `fn(args)` in a new coroutine with the `full_stack_size`-sized
+ * block of memory `stack` as the coroutine stack.
+ *
+ * There may be CPU-specific requirements on the alignment of the
+ * `stack` pointer.
+ *
+ * If CONFIG_COROUTINE_PROTECT_STACK: The usable stack size will be
+ * slightly less than `full_stack_size`, in order to make room for a
+ * stack guard at each end.
  *
  * See the doc comment on c_fn_t for the requirements imposed on fn.
  *
@@ -94,17 +102,35 @@ typedef void (*cr_fn_t)(void *args);
  * Returns the cid of the newly-created coroutine.  May return 0 if
  * there are already COROUTINE_NUM active coroutines.
  */
-cid_t coroutine_add_with_stack_size(size_t stack_size, const char *name, cr_fn_t fn, void *args);
+cid_t coroutine_add_with_stack(void *stack, size_t full_stack_size, const char *name, cr_fn_t fn, void *args);
+
+/**
+ * Like coroutine_add_with_stack(), but will use aligned_alloc() to
+ * allocate a block of memory to use as the stack.
+ *
+ * If CONFIG_COROUTINE_PROTECT_STACK: `usable_stack_size` does *not*
+ * include the size of the stack guard at each end; the amount of
+ * memory allocated for the stack will be slightly larger than
+ * `usable_stack_size`.
+ */
+cid_t coroutine_add_with_stack_size(size_t usable_stack_size, const char *name, cr_fn_t fn, void *args);
 
 /**
  * Like coroutine_add_with_stack_size(), but uses a default stack size so
  * you don't need to think about it.
  *
- * Either define CONFIG_COROUTINE_STACK_SIZE_DEFAULT to use for all
- * coroutines, or CONFIG_COROUTINE_STACK_SIZE_{fn} for each COROUTINE
- * function.
+ * Either:
+ *  - define CONFIG_COROUTINE_STACK_SIZE_DEFAULT to use for all
+ *    coroutines; or
+ *  - define/declare CONFIG_COROUTINE_STACK_SIZE_{fn} for each COROUTINE
+ *    function; or
+ *  - define CONFIG_COROUTINE_STACK_PREALLOCATE and then
+ *    define/declare COROUTINE_STACK_{fn} and COROUTINE_STACK_{fn}_len
+ *    for each COROUTINE function.
  */
-#ifdef CONFIG_COROUTINE_STACK_SIZE_DEFAULT
+#if defined(CONFIG_COROUTINE_STACK_PREALLOCATE)
+#define coroutine_add(name, fn, args) coroutine_add_with_stack(COROUTINE_STACK_##fn, COROUTINE_STACK_##fn##_len, name, fn, args)
+#elif defined(CONFIG_COROUTINE_STACK_SIZE_DEFAULT)
 #define coroutine_add(name, fn, args) coroutine_add_with_stack_size(CONFIG_COROUTINE_STACK_SIZE_DEFAULT, name, fn, args)
 #else
 #define coroutine_add(name, fn, args) coroutine_add_with_stack_size(CONFIG_COROUTINE_STACK_SIZE_##fn, name, fn, args)