Merge pull request #369 from ilovepi/frame-pointers

Specify the stack slot the frame pointer points to

Author: kito-cheng

riscv-cc.adoc

@@ -28,9 +28,42 @@ endif::[]
 In the standard ABI, procedures should not modify the integer registers tp and
 gp, because signal handlers may rely upon their values.
 
+=== Frame Pointer Convention
+
 The presence of a frame pointer is optional.  If a frame pointer exists,
 it must reside in x8 (s0); the register remains callee-saved.
 
+Code that uses a frame pointer will construct a linked list of stack frames,
+where each frame links to its caller using a "frame record". A frame record
+consists of two XLEN values on the stack; the return address and the link to
+the next frame record. The frame pointer register will point to the innermost
+frame, thereby starting the linked list. By convention, the lowest XLEN value
+shall point to the previous frame, while the next XLEN value shall be the
+return address. The end of the frame record chain is indicated by the address
+zero appearing as the next link in the chain.
+
+After the prologue, the frame pointer register will point to the Canonical
+Frame Address or CFA, which is the stack pointer value on entry to the current
+procedure. The previous frame pointer and return address pair will reside just
+prior to the current stack address held in `fp`. This puts the return address
+at `fp - XLEN/8`, and the previous frame pointer at `fp - 2 * XLEN/8`.
+
+It is left to the platform to determine the level of conformance with this
+convention. A platform may choose:
+
+- not to maintain a frame chain and use the frame pointer register as a general
+  purpose callee-saved register.
+
+- to allow the frame pointer register be used as a general purpose callee-saved
+  register, but provide a platform specific mechanism to reliably detect this
+  condition.
+
+- to use a frame pointer to address a valid frame record at all times, but
+  allow any procedure to choose to forgo creating a frame record.
+
+- to use the frame pointer to address a valid frame record at all times, except
+  leaf functions, who may elect to forgo creating a frame record.
+
 === Floating-point Register Convention
 
 .Floating-point register convention