Merge pull request #2005 from ghaerr/docs

[Documentation] Update function calling conventions and prologues

Documentation/text/parameter-passing.txt

@@ -1,19 +1,22 @@
-ELKS kernel
-    System call calling convention requires registers set in order of parameters:
+Parameter Passing and Calling Conventions
+=========================================
+
+ELKS kernel system calls
+    System call calling convention requires registers set in order of parameters,
+    regardless of which compiler is used:
         BX, CX, DX, DI, SI
-    AX is set to the system call number defined in elks/arch/i86/kernel/syscall.dat
-    Then execute INT 0x80.  Return value is in AX.
-    Error are indicated by negative errno (-errno) return values.
+    AX is set to the system call number defined in elks/arch/i86/kernel/syscall.dat,
+    then an INT 0x80 executed.  Return value is in AX.
+    Error are indicated by negative AX (-errno) return values.
 
 
 ia16-elf-gcc C compiler
-    Cdecl calling convention, stack has parms, passed in this order in registers:
-        BX, CX, DX, DI, SI
-        caller pops all args after call
+    Cdecl (default) calling convention: stack has parms, passed in reverse order,
+        caller pops all args after call.
 
-    Regparmcall calling convention, args passed in following registers in order:
+    Regparmcall calling convention: args passed in following registers in order:
         AX, DX, CX, DI, SI
-        callee pops args > 3 before return!
+        callee pops args > 3 before return.
 
 
 OpenWatcom C compiler
@@ -33,3 +36,62 @@ OpenWatcom C compiler
         write(int, char __far *, int)  uses AX, CX:BX, DX
 
     Compiler also supports __stdcall like __cdecl except callee pops args on return.
+
+
+Function Prologues Produced by C Compilers
+==========================================
+
+Possible ia16-elf-gcc function prologues
+----------------------------------------
+
+SI only
+ 193:   56                      push   %si
+
+SI & DI only
+   0:   56                      push   %si
+   1:   57                      push   %di
+
+NORMAL
+   0:   55                      push   %bp
+   1:   89 e5                   mov    %sp,%bp
+
+NORMAL w/SI
+  3d:   56                      push   %si
+  3e:   55                      push   %bp
+  3f:   89 e5                   mov    %sp,%bp
+
+NORMAL w/SI & DI
+ 13e:   56                      push   %si
+ 13f:   57                      push   %di
+ 140:   55                      push   %bp
+ 141:   89 e5                   mov    %sp,%bp
+
+NORMAL w/SI & DI and small locals
+ 1c4:   56                      push   %si
+ 1c5:   57                      push   %di
+ 1c6:   55                      push   %bp
+ 1c7:   89 e5                   mov    %sp,%bp
+ 1c9:   83 ec 24                sub    $0x24,%sp
+
+NORMAL w/SI & DI and large locals
+  6d:   56                      push   %si
+  6e:   57                      push   %di
+  6f:   55                      push   %bp
+  70:   89 e5                   mov    %sp,%bp
+  72:   81 ec 84 00             sub    $0x84,%sp
+
+
+Function start address determination for backtrace
+--------------------------------------------------
+
+Suggested algorithm for calculating function start:
+Search for 55 89 e5 in reverse order at IP-3 (NORMAL), IP-6 (NORMAL w/small locals)
+and IP-6 (NORMAL w/large locals).
+If found, BP_PUSHED, IP=matched IP;
+Then search for 57 DI_PUSHED, --IP;
+then search for 56 SI_PUSHED, --IP;
+Last location (IP) is then function start.
+
+Use -finstrument-functions-simple.          # function profiling
+Possibly use -fno-omit-frame-pointer.       # always push BP in prologue
+Possibly use -fno-optimize-sibling-calls.   # disable tail call optimization