a

1 files changed, 9 insertions, 0 deletions

diff --git a/docs/design/struct-by-value.md b/docs/design/struct-by-value.md
new file mode 100644
index 0000000..bbc8f26
--- /dev/null
+++ b/docs/design/struct-by-value.md
@@ -0,0 +1,9 @@
+# structs in native calls
+
+zc structs whose fields are one word each (`int`, `float` or pointers) can be passed by value to `extern` functions, and native functions can return structs. the interpreter, o3, llvm and jit paths support sysv x86-64 and linux arm64 aapcs64. apple arm64 is not verified.
+
+arguments are classified according to the host ABI. on sysv x86-64, structs up to 16 bytes use integer or sse registers when the whole value fits; otherwise they go on the stack. larger structs go on the stack. on aapcs64, homogeneous float structs of up to four words use v registers, integer structs of up to two words use x registers, and other arguments follow the platform ABI.
+
+returns are limited to seven words. the call stub allocates an owned zc object and passes its address through the call block; the native ABI determines how the result is filled. the llvm descriptor path does not handle grouped struct signatures, so these calls use the generic native-call path.
+
+see `tests/programs/structval.zc` and `tests/programs/structret.zc` for executable examples. platform-specific behavior beyond x86-64 sysv and linux arm64 aapcs64 remains unverified.