Test stackman_call's return value and previous stack pointer. (#21)

* Test stackman_call's return value and previous stack pointer.

test_04 and test_05 now check that the callback result comes back
unchanged, that a caller local survives writes on the alternate stack,
and that the pointer argument is the previous stack. The audit note
records the register findings these checks come from.

qemu-riscv64 is expected to fail until switch_riscv64_gcc.S skips a
null stack and passes the previous stack pointer.

* update docs

* fix riscv64 headers

* Fix RISC-V stackman_call so the qemu tests can pass.

A null stack was installed as sp, which faulted test_05, and the callback
received that new pointer instead of the previous one, which failed
test_04. Skip a zero stack and pass the saved stack pointer.

* Stop Windows ARM64 from writing the live TEB register.

x18 is the TEB for the whole time user code runs. stackman_switch now
keeps the callback in x20, and stackman_call keeps the old stack pointer
in x19. Both routines still spill and restore x18 so a switched context
gets the value it saved. SEH unwind codes are unchanged.

* Keep the AArch64 frame pointer attached across a stack switch.

stackman_switch now applies the stack delta to x29 before the restore
callback, in the checked-in assembly and in the inline sequence that
generates it. The epilogue still reloads the saved x29. SME lazy save
is left for a target that enables SME.

* Spill MXCSR in the Windows x64 stack switch.

The control bits of MXCSR are non-volatile. stackman_switch stores the
register in the unused 8-byte slot at the top of the xmm frame and loads
it back before releasing that frame, including after the stack has moved.
stackman_call returns to the same caller and does not spill it.

* Spill the i386 x87 control word with the stack image.

SysV stores it with fstcw at the pointer passed to the callback, in both
the checked-in assembly and the inline block it is copied from. Windows
does the same inside stackman_switch_raw, next to the callee-saved
pushes, and the C wrapper still restores the SEH chain. XMM registers
stay unsaved.

* Reject ARM32 hard-float and keep r11 attached across a switch.

The checked-in assembly is soft-float and does not spill d8-d15, so a
__ARM_PCS_VFP include is now a compile error. stackman_switch applies
the stack delta to r11 before the restore callback. The RISC-V s0 delta
stays omitted: s0 is not a frame chain there, and stackman_call uses it
for the previous stack pointer.

* Remove the dropped Windows ARM32 switch.

CHANGELOG 1.0.0 already dropped win_arm. The sources were still selected
for _M_ARM, and the VS projects still built them. That assembly pushed an
odd number of registers and then vpush'd at 4 mod 8. Delete the sources,
the platform branch, the Debug|ARM project configurations, and the
prebuilt lib/win_arm archive. Windows ARM64 is unchanged.

* update ZA information

* Replace the Copilot instructions with a root AGENTS.md.

The Copilot file still described version 1.0.1, seven ABIs, and six tests, and told agents to trust it ahead of the tree. AGENTS.md points at the current sources instead. The Copilot path is a short pointer so that file does not drift again.

* commit za comment

* Drop the ARM32 r11 adjust from the stack switch.

stackman_switch is built with omit-frame-pointer. The prologue pushes fp and never sets it, so live r11 is not this frame, and the epilogue pops the saved value. The inline build can keep the callback or the new stack pointer in r11, and the delta then corrupts it before the restore callback. AArch64 still adjusts x29, which the prologue sets from sp.

* Correct the i386 fstcw comment.

fstcw is FWAIT plus FNSTCW, so it does wait on a pending unmasked x87 exception. The spill stays fstcw, matching switch_x86_64_gcc.S, which delivers that exception on this stack before the switch.

Author: kristjanvalur

.github/copilot-instructions.md

@@ -1,139 +1,4 @@
-# Copilot Instructions for stackman
+# Copilot instructions
 
-## Overview
-Low-level C library for stack manipulation (continuations/co-routines). ~600 lines of C + assembly. Zero dependencies. **Current version: 1.0.1**
-
-**Supported Platforms (7 ABIs):**
-- Linux: sysv_amd64, sysv_i386, arm32 (AAPCS), aarch64 (AAPCS64)
-- Windows: win_x86, win_x64, win_arm64
-
-**Note:** Windows ARM32 (win_arm) support was removed in v1.0.0 (Microsoft SDK 10.0.26100.0+ dropped support)
-
-**Toolchains:** GCC, Clang, MSVC (VS2017, VS2019, VS2022)
-
-## Build Commands (FAST: <1 second)
-
-**Always run in order:**
-```bash
-make clean      # Clean build artifacts
-make all        # Build library (0.1s) → lib/[ABI]/libstackman.a
-make test       # Build + run 4 test suites (0.7s)
-make abiname    # Print platform ABI (e.g., sysv_amd64)
-```
-
-**Success output:** `*** All test suites passed ***`
-
-**Cross-compile x86:** `make PLATFORMFLAGS=-m32 test`
-**Cross-compile ARM:** `make PLATFORM_PREFIX=arm-linux-gnueabi- EMULATOR=qemu-arm test`
-**Windows:** `msbuild vs2022\stackman.sln /p:Platform=x64` then `vs2022\x64\Debug\test.exe`
-
-## Critical Build Notes
-
-1. **Intel CET:** `-fcf-protection=none` flag REQUIRED (auto-added by disable_cet script). Stack switching incompatible with Shadow Stack.
-2. **Libraries Deprecated in Repo:** As of v1.0.1, pre-built libraries are NO LONGER automatically committed. Download from [GitHub Releases](https://github.com/stackless-dev/stackman/releases) instead. `lib/` directory will be removed in v2.0.0.
-3. **Expected Warning:** Linker warning "missing .note.GNU-stack section" in test_asm is NORMAL - ignore it.
-4. **Artifacts:** `*.o`, `bin/`, `tmp/` NOT committed. Libraries available via GitHub Releases.
-5. **Incremental OK:** After code changes, just `make test`. Only clean when switching platforms.
-
-## Project Structure
-
-**Key Directories:**
-- `stackman/` - Main source: `stackman.h` (API + version macros), `stackman_switch.h`, `stackman_impl.h`, `platforms/` (15+ platform files)
-- `tests/` - 4 test files: `test.c` (6 tests), `test_cc.cc`, `test_static.c`, `test_asm.c/.S`
-- `lib/[ABI]/` - Pre-built libraries (DEPRECATED - see lib/README.md, will be removed in v2.0.0)
-- `vs2017/`, `vs2019/`, `vs2022/` - Visual Studio projects
-- `tools/` - `abiname.sh`, `abiname.c`, `strip-lib.py`
-
-**Core API (2 functions only):**
-```c
-void *stackman_switch(stackman_cb_t callback, void *context);  // Main stack switch
-void *stackman_call(stackman_cb_t callback, void *context, void *stack);  // Call with different stack
-```
-
-**Architecture:** `platforms/platform.h` detects OS/arch/compiler → includes appropriate `switch_[abi]_[compiler].h/S/asm`
-
-## CI Validation (.github/workflows/buildcommit.yml)
-
-**Triggers:** Push to master/dev, PRs to master, tags (v*.*.*)
-
-**Jobs:**
-1. **build-linux-gnu** (sysv_amd64, sysv_i386, arm32, aarch64) - installs cross-tools → `make all` → `make test` (qemu for ARM)
-2. **build-windows** (win_x86, win_x64, win_arm64) - MSBuild → strip-lib.py → rebuild (MUST rebuild after strip!)
-3. **commit-artifacts** (DISABLED as of v1.0.1) - Previously committed libs to repo, now disabled (if: false)
-4. **create-release** (tags only) - Creates GitHub Release with `stackman-{version}.tar.gz` containing all platforms
-
-**Release Archive Contents:**
-- `stackman/` - Headers
-- `lib/{abi}/` - Pre-built libraries for all 7 platforms
-- `tools/` - Platform detection tools
-- `Makefile` - For `make abiname`
-- Documentation (README.md, LICENSE, CHANGELOG.md)
-
-**Local validation:**
-```bash
-make clean && make test  # Test native platform
-git status               # Verify no bin/, tmp/, *.o tracked
-```
-
-## Key Patterns & Workarounds
-
-**Making Changes:**
-- Platform code: edit `stackman/platforms/switch_*.h` or `.S` - reference `switch_template.h`
-- Always run `make test` after changes (fast: 0.7s)
-- Test on actual hardware if modifying assembly (arch-specific!)
-
-**Known Issues/Workarounds:**
-- **CET:** `-fcf-protection=none` REQUIRED (auto-added by disable_cet script)
-- **Inline asm:** May be inlined by optimizer → use separate .S files or volatile pointer (see stackman_impl.h)
-- **Stack align:** Use `STACKMAN_SP_ALIGN` macro
-
-**Testing:** 4 test executables, 6 tests each (assertions fail hard). Success: "test_XX ok" + "*** All test suites passed ***"
-
-**Include patterns:**
-- User code: `#include "stackman.h"`
-- Library impl: `#include "stackman_impl.h"` (once)
-
-## Configuration Files
-- **Build:** Makefile (Linux), vs2022/*.vcxproj (Windows)
-- **CI:** .github/workflows/buildcommit.yml
-- **Versioning:** stackman/stackman.h - STACKMAN_VERSION_MAJOR/MINOR/PATCH macros + STACKMAN_VERSION string
-- **Changelog:** CHANGELOG.md (documents all releases)
-- **Linting:** None configured
-- **Testing:** `make test` target
-- **.gitignore:** Excludes *.o, bin/, tmp/ BUT still includes lib/**/*.a, lib/**/*.lib (deprecated, slated for removal)
-
-## Development Tips
-
-1. **Trust these instructions first** - search only if info incomplete/incorrect
-2. **Build is FAST** - rebuild freely (clean+test <1s)
-3. **Test after every change** - `make test` is fast and comprehensive
-4. **Cross-compilation optional** - CI validates all platforms, native x64 sufficient for most changes
-5. **No binary commits** - lib/ directory deprecated, use GitHub Releases
-6. **Zero dependencies** - don't add any
-7. **Minimal changes** - stable library, surgical edits only
-8. **Low-level code** - assembly is platform-specific, test on actual hardware
-
-## Versioning & Releases
-
-**Version Location:** `stackman/stackman.h`
-```c
-#define STACKMAN_VERSION_MAJOR 1
-#define STACKMAN_VERSION_MINOR 0
-#define STACKMAN_VERSION_PATCH 1
-#define STACKMAN_VERSION "1.0.1"
-```
-
-**Release Process:**
-1. Update version in `stackman/stackman.h` (MAJOR.MINOR.PATCH)
-2. Update `CHANGELOG.md` with changes
-3. Commit changes: `git commit -m "Bump version to X.Y.Z"`
-4. Create tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"`
-5. Push: `git push upstream master && git push upstream vX.Y.Z`
-6. CI automatically creates GitHub Release with pre-built libraries
-
-**Version History:**
-- v0.1 (2020-05-18) - Initial release
-- v0.2 (retroactive tag) - Pre-1.0 development state
-- v1.0.0 (2025-11-16) - First stable release, removed Windows ARM32
-- v1.0.1 (2025-11-16) - Disabled library commits, use GitHub Releases
-- v2.0.0 (future) - Will remove lib/ directory entirely
+The project instructions are in [AGENTS.md](../AGENTS.md) at the
+repository root. Read that file. Do not keep a second copy here.

AGENTS.md

@@ -0,0 +1,143 @@
+# Agent notes for stackman
+
+Low-level C library for stack switching. Two functions, no dependencies.
+Read the sources. This file is a map, not a second copy of them. The
+version is `STACKMAN_VERSION` in `stackman/stackman.h`.
+
+## What the library does
+
+`stackman_switch` saves callee-saved state, calls the callback with
+`STACKMAN_OP_SAVE`, installs the stack pointer that callback returns,
+calls it again with `STACKMAN_OP_RESTORE`, then restores the saved state
+and returns that second result. It may resume a different caller, so the
+spill is the whole non-volatile set for that ABI.
+
+`stackman_call` runs the callback on another stack and returns to the
+same caller. A null stack is left unchanged. The pointer passed to the
+callback is the previous stack pointer. It only needs to preserve
+registers it modifies.
+
+User code includes `stackman.h`. The library implementation includes
+`stackman_impl.h` once. `platforms/platform.h` selects
+`switch_<abi>_<compiler>`.
+
+`STACKMAN_HAVE_CALL` and `STACKMAN_STACK_ALIGN` must be visible from a
+normal `#include "stackman.h"`. If they sit under
+`#ifdef STACKMAN_SWITCH_IMPL`, `tests/test.c` compiles `stackman_call`
+out and CI looks green.
+
+Align a stack with `STACKMAN_SP_ALIGN`. It follows `STACKMAN_STACK_ALIGN`
+and the stack direction.
+
+## Platforms
+
+Linux: `sysv_i386`, `sysv_amd64`, `arm32` (soft-float AAPCS), `aarch64`,
+`riscv64` (LP64D). macOS: `darwin_x86_64`, `darwin_arm64`. Windows:
+`win_x86`, `win_x64`, `win_arm64`. `win_aarch64` is accepted and
+normalized to `win_arm64`. FreeBSD, OpenBSD, and NetBSD use the Linux
+`sysv_amd64` sources. Their workflow runs `gmake`.
+
+Windows ARM32 (`win_arm`) was removed in 1.0.0. Do not add it back.
+
+The default build uses the checked-in `.S` and `.asm` files.
+`STACKMAN_INLINE_ASM` is unset. RISC-V always uses
+`switch_riscv64_gcc.S`. When a `.S` is generated from a header, change
+the header and the `.S` together. `gen_asm.c` defines
+`STACKMAN_INLINE_ASM` as 1. A `.S` `#` line comment is a snapshot of the
+header line and goes stale if lines are inserted above the asm. Leave
+those comments unless you are regenerating the file.
+
+## Register contract
+
+Volatile registers may change. Do not add a test that treats them as
+preserved.
+
+Details and the original audit are in `docs/abi-register-audit.md`.
+Limits that are easy to fix the wrong way:
+
+- ARM32 hard-float is unsupported. `switch_arm_gcc.S` is `.arch armv5t`
+  and `.fpu softvfp`, and it does not spill `d8`–`d15`. `__ARM_PCS_VFP`
+  is a compile error. A hard-float port is a new assembly file with its
+  own ABI name. Softfp does not define `__ARM_PCS_VFP`, and the compiler
+  can still use `d8`–`d15`.
+- `aarch64`, `darwin_arm64`, and `win_arm64` do not preserve SME ZA
+  across `stackman_switch`. Do not call `__arm_za_disable`. That helper
+  commits the outgoing caller's ZA and turns ZA off. Nothing in the
+  switch installs the incoming stack's ZA. `stackman_call` returns to
+  the same caller and does not need it. Windows ARM64 is a different
+  runtime. Do not call the AAPCS64 helper there.
+- On Windows ARM64, `x18` is the TEB for the whole time user code runs.
+  Spill and restore the saved value. Do not write the live register.
+  Do not invent `.seh_*` names for this file.
+- A live frame pointer (`x29` on AArch64) is adjusted by the stack delta
+  inside the asm. Do not list `x29` as a clobber. Do not adjust ARM32
+  `r11` there: `stackman_switch` is built with `omit-frame-pointer`, the
+  prologue pushes `r11` and never sets it, and the epilogue reloads the
+  saved value. On RISC-V, `s0` is not a frame chain in
+  `stackman_switch`, and `stackman_call` uses `s0` for the previous
+  stack pointer. Do not adjust it there.
+- AAPCS64 FPCR and RISC-V `fcsr` are thread state. They are not per-call
+  spills.
+
+## Build and test
+
+```bash
+make test          # native ABI. Builds lib/$(ABI)/libstackman.a and runs the tests.
+make abiname
+make PLATFORMFLAGS=-m32 test
+make PLATFORM_PREFIX=arm-linux-gnueabi- EMULATOR=qemu-arm test
+```
+
+`make clean` only when switching `PLATFORMFLAGS` or `PLATFORM_PREFIX`.
+Success ends with `*** All test suites passed ***`.
+
+Four programs: `bin/test`, `bin/test_cc`, `bin/test_static`,
+`bin/test_asm`. `tests/test.c` is `test_01` through `test_08`. `test_04`
+and `test_05` are the `stackman_call` contract. `test_07` and `test_08`
+pressure the compiler. They pass even when a callee-saved register is
+dropped, if the compiler kept the values in memory.
+
+The linker warning `missing .note.GNU-stack section` on
+`tests/test_asm_s.o` is expected.
+
+Intel CET: the Makefile adds `-fcf-protection=none` through
+`./disable_cet`. Stack switching is incompatible with the shadow stack.
+Regenerating asm uses the same flag (`gcc -S -fcf-protection=none`).
+
+Windows, as CI runs it: `msbuild vs2022\stackman.sln /p:Platform=x64`
+(also `x86` and `arm64`). Native tests are `vs2022\x64\Debug\test.exe`
+and `vs2022\Win32\Debug\test.exe`. The arm64 build is not run. After
+`tools/strip-lib.py`, CI rebuilds.
+
+Do not commit rebuilt `lib/` archives, `*.o`, `bin/`, or `tmp/`.
+Checked-in libraries under `lib/` are deprecated and go away in a future
+major version. `commit-artifacts` in
+`.github/workflows/buildcommit.yml` is `if: false`.
+
+## CI
+
+`.github/workflows/buildcommit.yml`, on pull requests to `master`:
+
+- `build-linux-gnu`: AMD64, i386 (`-m32`), arm (`qemu-arm`), aarch64
+  (`qemu-aarch64`), riscv64 (`qemu-riscv64`). Each runs `make test`.
+- `build-macos`: `macos-15-intel` (`darwin_x86_64`) and `macos-latest`
+  (`darwin_arm64`).
+- `build-windows`: VS2022 `x86`, `x64`, and `arm64`. Tests run only
+  where `native` is set (`x86` and `x64`).
+
+`.github/workflows/buildbsd.yml` builds and tests FreeBSD, OpenBSD, and
+NetBSD with `gmake` on the `sysv_amd64` sources.
+
+A green native `make test` says nothing about another ABI. An assembly
+change is checked by the job that builds that file.
+
+## Edits
+
+Keep changes small. Do not add a dependency. Do not bump `stackman.h` or
+`CHANGELOG.md` unless asked.
+
+Prefer the checked-in assembly over turning `STACKMAN_INLINE_ASM` on.
+`switch_template.h` is the skeleton for a new port.
+
+There is no `main` branch. `master` is the default on both `origin`
+(`kristjanvalur/stackman`) and `upstream` (`stackless-dev/stackman`).

README.md

@@ -59,7 +59,7 @@ platforms so that no assembly steps are required by users.
     straightforward implementation on most platforms.
   - Complex logic and branching is delegated to the C callback.
   - Custom platform assembly code must only do three things:
-    1. Save and restore volatile registers and stack state on the stack
+    1. Save and restore callee-saved (non-volatile) registers and stack state on the stack
     2. Call the callback twice with the current stack pointer
     3. Set the stack pointer to the value returned by the first callback.
 
@@ -105,6 +105,9 @@ calling convention, plus archive format:
  - **FreeBSD, OpenBSD, NetBSD (System V ABI)**
    - sysv_amd64 (64-bit x86_64)
 
+The 64-bit ARM ABIs (`aarch64`, `darwin_arm64`, and `win_arm64`) do not
+preserve SME ZA context across `stackman_switch`.
+
 All platforms are automatically built and tested by GitHub Actions CI on every commit.
 
 The BSDs share the `sysv_amd64` ABI with Linux and therefore need no separate
@@ -157,7 +160,9 @@ use.
 
 1. It saves the current CPU stack pointer.  If `stack` is non-zero, it will replace the stackpointer
 with that value.
-2. It calls the callback function with the opcode `STACKMAN_OP_CALL`.
+2. It calls the callback function with the opcode `STACKMAN_OP_CALL`. The
+   stack pointer argument is the previous stack pointer, the one in use before
+   this call. A null `stack` leaves that pointer unchanged.
 3. It replaces the stack pointer with the previously saved value and returns the return value from the callback.
 
 This function is useful for at least three things: