docs: Add docs for stack.h

This does not include documentation for `emscripten_stack_init()`
as this appears to be for use internally within emscripten.

Author: waywardmonkeys

site/source/docs/api_reference/index.rst

@@ -48,6 +48,9 @@ high level it consists of:
 - :ref:`proxying-h`:
   API for synchronously or asynchronously proxying work to a target pthread.
 
+- :ref:`stack-h`:
+  Inspecting the WebAssembly data stack.
+
 - :ref:`api-reference-advanced-apis`:
   APIs for advanced users/core developers.
 
@@ -66,6 +69,7 @@ high level it consists of:
    trace.h
    fiber.h
    proxying.h
+   stack.h
    wasm_workers
    wasm_audio_worklets
    advanced-apis

site/source/docs/api_reference/stack.h.rst

@@ -0,0 +1,41 @@
+.. _stack-h:
+
+=======
+stack.h
+=======
+
+The functions defined in `<emscripten/stack.h>` allow inspecting
+information about the WebAssembly data stack (sometimes called the
+"user stack" or the "C stack"). This data stack is the data contained
+within the linear memory (as opposed to the trusted call stack that
+is managed by the VM, and which is not visible to the running program).
+
+.. c:function:: uintptr_t emscripten_stack_get_base(void)
+
+  Returns the starting address of the stack. This is the address
+  that the stack pointer would point to when no bytes are in use on the
+  stack.
+
+.. c:function:: uintptr_t emscripten_stack_get_end(void)
+
+  Returns the end address of the stack. This is the address that
+  the stack pointer would point to when the whole stack is in use. (The
+  address pointed to by the end is not part of the stack itself). Note
+  that the stack grows down so the address returned by
+  `emscripten_stack_get_end()` is smaller than
+  :c:func:`emscripten_stack_get_base()`.
+
+.. c:function:: void emscripten_stack_set_limits(void* base, void* end)
+
+  Sets the internal values reported by :c:func:`emscripten_stack_get_base()`
+  and :c:func:`emscripten_stack_get_end()`.  This should only used by low
+  level libraries such as asyncify fibers.
+
+.. c:function:: uintptr_t emscripten_stack_get_current(void)
+
+  Returns the current stack pointer.
+
+.. c:function:: size_t emscripten_stack_get_free(void)
+
+  Returns the number of free bytes left on the stack.  This is required
+  to be fast so that it can be called frequently.

system/include/emscripten/stack.h

@@ -16,25 +16,25 @@
 extern "C" {
 #endif
 
-// Returns the starting address of the wasm stack. This is the address
+// Returns the starting address of the stack. This is the address
 // that the stack pointer would point to when no bytes are in use on the stack.
 uintptr_t emscripten_stack_get_base(void);
 
-// Returns the end address of the wasm stack. This is the address that the stack
+// Returns the end address of the stack. This is the address that the stack
 // pointer would point to when the whole stack is in use.  (the address pointed
 // to by the end is not part of the stack itself). Note that the stack grows
 // down so the address returned by emscripten_stack_get_end() is smaller than
 // emscripten_stack_get_base().
 uintptr_t emscripten_stack_get_end(void);
 
 // Setup internal base/end values based on the initial values that were either
-// set at compile time (in static linking) or instantiations time (for dynamic
+// set at compile time (in static linking) or instantiation time (for dynamic
 // linking).
 void emscripten_stack_init(void);
 
-// Sets the internal values reported by emscripten_stack_get_base and
-// emscripten_stack_get_end.  This should only used by low level libraries
-// such as asyncify fibres.
+// Sets the internal values reported by emscripten_stack_get_base() and
+// emscripten_stack_get_end().  This should only used by low level libraries
+// such as asyncify fibers.
 void emscripten_stack_set_limits(void* base, void* end);
 
 // Returns the current stack pointer.