Document STACKMAN_SP_FURTHEST/NEAREST overflow risk

Add comprehensive documentation warning that STACKMAN_SP_FURTHEST and
STACKMAN_SP_NEAREST are sentinel values that should only be used for
comparison operations (SP_LS, SP_LE) and never for arithmetic operations
(SP_ADD, SP_DIFF) due to risk of pointer overflow when operating on
addresses at extreme ends of the address space.

Author: kristjanvalur

stackman/stackman.h

@@ -84,6 +84,24 @@
 #define STACKMAN_SP_ALIGN_DOWN(a) (((intptr_t)(a) & ~(STACKMAN_STACK_ALIGN-1)))
 #define STACKMAN_SP_ALIGN_UP(a)	  (((intptr_t)((a)+STACKMAN_STACK_ALIGN-1) & ~(STACKMAN_STACK_ALIGN-1)))
 
+/* Stack pointer manipulation macros that work for both descending and ascending stacks.
+ * 
+ * STACKMAN_SP_FURTHEST and STACKMAN_SP_NEAREST are sentinel values representing the
+ * theoretical limits of the stack address space. These should be used for initialization
+ * and comparison only.
+ * 
+ * WARNING: Do NOT use STACKMAN_SP_FURTHEST or STACKMAN_SP_NEAREST with STACKMAN_SP_ADD
+ * or STACKMAN_SP_DIFF operations, as these sentinel values are at the extreme ends of
+ * the address space and arithmetic operations with them can cause pointer overflow and
+ * undefined behavior.
+ * 
+ * Safe operations with FURTHEST/NEAREST: STACKMAN_SP_LS, STACKMAN_SP_LE (comparison)
+ * Unsafe operations: STACKMAN_SP_ADD, STACKMAN_SP_DIFF (arithmetic)
+ * 
+ * For actual stack boundaries, use real pointer values (e.g., address of a stack variable).
+ * The sentinel values can be used instead if the stack bounds are unknown, but then the value
+ * should always be checked first for the sentinel value before performing any arithmetic operations.
+ */
 #if STACKMAN_STACK_DIR == 0
 #define STACKMAN_SP_FURTHEST      ((void*) (intptr_t) -STACKMAN_STACK_ALIGN)
 #define STACKMAN_SP_NEAREST       ((void*) 0)