From 83cf4b9d57109ac95d64920fcb886b37c591a721 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Lindqvist?= <bjourne@gmail.com>
Date: Tue, 14 Oct 2014 17:37:46 +0200
Subject: [PATCH] compiler,cpu: more docs

---
 .../builder/alien/params/params-docs.factor   | 17 +++++++++++
 .../cpu/architecture/architecture-docs.factor | 29 ++++++++++++++++++-
 basis/cpu/x86/x86-docs.factor                 |  4 +++
 3 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 basis/compiler/cfg/builder/alien/params/params-docs.factor

diff --git a/basis/compiler/cfg/builder/alien/params/params-docs.factor b/basis/compiler/cfg/builder/alien/params/params-docs.factor
new file mode 100644
index 0000000000..f6599ebc11
--- /dev/null
+++ b/basis/compiler/cfg/builder/alien/params/params-docs.factor
@@ -0,0 +1,17 @@
+USING: cpu.architecture help.markup help.syntax math ;
+IN: compiler.cfg.builder.alien.params
+
+HELP: stack-params
+{ $var-description "Count of the number of bytes of stack allocation required to store the current call frames parameters." } ;
+
+HELP: alloc-stack-param
+{ $values { "rep" representation } { "n" integer } }
+{ $description "Allocates space for a stack parameter value of the given representation and returns the previous stack parameter offset." }
+{ $examples
+  "On 32-bit architectures, the offsets will be aligned to four byte boundaries."
+  { $unchecked-example
+    "0 stack-params set float-rep alloc-stack-param stack-params get . ."
+    "4"
+    "0"
+  }
+} ;
diff --git a/basis/cpu/architecture/architecture-docs.factor b/basis/cpu/architecture/architecture-docs.factor
index 6e2f8aa89c..c8e29dc13f 100644
--- a/basis/cpu/architecture/architecture-docs.factor
+++ b/basis/cpu/architecture/architecture-docs.factor
@@ -1,4 +1,4 @@
-USING: assocs compiler.cfg.instructions cpu.x86.assembler
+USING: assocs alien compiler.cfg.instructions cpu.x86.assembler
 cpu.x86.assembler.operands help.markup help.syntax kernel
 layouts literals math multiline system words ;
 IN: cpu.architecture
@@ -134,3 +134,30 @@ HELP: fused-unboxing?
 HELP: return-regs
 { $values { "regs" assoc } }
 { $description "What registers that will be used for function return values of which class." } ;
+
+HELP: stack-cleanup
+{ $values { "stack-size" integer } { "return" "a c type" } { "abi" abi } }
+{ $description "Calculates how many bytes of stack space the caller of the procedure being constructed need to cleanup. For modern abi's the value is almost always 0." }
+{ $examples
+  { $unchecked-example
+    "USING: cpu.architecture prettyprint ;"
+    "20 void stdcall stack-cleanup ."
+    "20"
+  }
+} ;
+
+ARTICLE: "cpu.architecture" "CPU architecture description model"
+"The " { $vocab-link "cpu.architecture" } " vocab generic words and hooks that serves as an api for the compiler towards the cpu architecture."
+$nl
+"Register categories:"
+{ $subsections machine-registers param-regs return-regs }
+"Architecture support checks:"
+{ $subsections
+  complex-addressing?
+  float-on-stack?
+  float-right-align-on-stack?
+  fused-unboxing?
+  test-instruction?
+}
+"Control flow code emitters:"
+{ $subsections %call %jump %jump-label %return } ;
diff --git a/basis/cpu/x86/x86-docs.factor b/basis/cpu/x86/x86-docs.factor
index 5b0f72b2cd..9e904eac7a 100644
--- a/basis/cpu/x86/x86-docs.factor
+++ b/basis/cpu/x86/x86-docs.factor
@@ -7,6 +7,10 @@ HELP: stack-reg
   "Symbol of the machine register that holds the (cpu) stack address."
 } ;
 
+HELP: reserved-stack-space
+{ $values { "n" integer } }
+{ $description "Size in bytes of the register parameter area. It only exists on the windows x86.64 architecture, where it is 32 bytes and allocated by the caller. On all other platforms it is 0." } ;
+
 HELP: ds-reg
 { $values { "reg" "a register symbol" } }
 { $description