pull out api.h into arch and add documentation

5 files changed, 36 insertions, 21 deletions

diff --git a/lib/arch.h b/lib/arch.h
index 524d401..a02fdba 100644
--- a/lib/arch.h
+++ b/lib/arch.h
@@ -7,11 +7,13 @@ static_assert(false, "Matcha Threads only supported on Linux!");
 #endif
 
 #if defined(__x86_64__) || defined(__amd64__)
-#    include "arch/x86_64/api.h"
+// fall-through: x86_64 support
 #elif defined(__aarch64__)
-#    include "arch/arm64/api.h"
+// fall-through: arm64 support
 #elif defined(__arm__)
-#    include "arch/arm/api.h"
+// fall-through: armv7 support
 #else
 static_assert(false, "Unsupported architecture!");
 #endif
+
+#include "arch/api.h"
diff --git a/lib/arch/api.h b/lib/arch/api.h
new file mode 100644
index 0000000..adf773e
--- /dev/null
+++ b/lib/arch/api.h
@@ -0,0 +1,31 @@
+/* Copyright (c) 2021 Johannes Stoelp */
+
+#pragma once
+
+// Platform specific API.
+// When integrating a new platform the following functions must be implemented.
+
+// Called once for every `Thread` object to setup the initial state of the
+// threads stack.
+//
+// Arguments:
+//   stack_ptr    Pointer to the bottom of the stack.
+//   entry        Function pointer to the entry-point called on first `yield`.
+//   ctx          Context passed to `entry`.
+//
+// Return:
+//   Return pointer to the top of the stack after initialization.
+//
+// Requirements:
+//   - Stack must be descending.
+//   - Returned stack pointer must be aligned according to the platform specification.
+//   - Stack must be setup in a way that a consequent call to `yield` will call
+//     `entry` with `ctx` supplied as argument.
+void* init_stack(void* stack_ptr, void (*entry)(void*), const void* ctx);
+
+// Switch execution context from current stack to `new_stack`.
+//
+// Arguments:
+//   new_stack    Stack pointer of new context to switch to.
+//   old_stack    Pointer to location to store the current stack pointer.
+extern "C" void yield(const void* new_stack, void** old_stack);
diff --git a/lib/arch/arm/api.h b/lib/arch/arm/api.h
deleted file mode 100644
index c7a688d..0000000
--- a/lib/arch/arm/api.h
+++ /dev/null
@@ -1,6 +0,0 @@
-/* Copyright (c) 2021 Johannes Stoelp */
-
-#pragma once
-
-extern "C" void yield(const void* new_stack, void** old_stack);
-void* init_stack(void* stack_ptr, void (*entry)(void*), const void* ctx);
diff --git a/lib/arch/arm64/api.h b/lib/arch/arm64/api.h
deleted file mode 100644
index 729bd1a..0000000
--- a/lib/arch/arm64/api.h
+++ /dev/null
@@ -1,6 +0,0 @@
-/* Copyright (c) 2020 Johannes Stoelp */
-
-#pragma once
-
-extern "C" void yield(const void* new_stack, void** old_stack);
-void* init_stack(void* stack_ptr, void (*entry)(void*), const void* ctx);
diff --git a/lib/arch/x86_64/api.h b/lib/arch/x86_64/api.h
deleted file mode 100644
index 729bd1a..0000000
--- a/lib/arch/x86_64/api.h
+++ /dev/null
@@ -1,6 +0,0 @@
-/* Copyright (c) 2020 Johannes Stoelp */
-
-#pragma once
-
-extern "C" void yield(const void* new_stack, void** old_stack);
-void* init_stack(void* stack_ptr, void (*entry)(void*), const void* ctx);