[PATCH] sh-tdep.c: add comment

[Elena Zannoni <ezannoni at redhat dot com>]

This adds a comment explaining the ABI convention for returning values.
This is taken from an old thread:
http://sources.redhat.com/ml/gdb/2002-09/msg00430.html

elena

2003-10-09  Elena Zannoni  <ezannoni@redhat.com>

	Based on input by Stephen Clarke (stephen.clarke@superh.com):
	* sh-tdep.c (sh_use_struct_convention): Add comment explaining ABI
	in detail.

Index: sh-tdep.c
===================================================================
RCS file: /cvs/uberbaum/gdb/sh-tdep.c,v
retrieving revision 1.145
diff -u -p -r1.145 sh-tdep.c
--- sh-tdep.c	3 Oct 2003 08:13:37 -0000	1.145
+++ sh-tdep.c	9 Oct 2003 19:32:39 -0000
@@ -559,7 +543,47 @@ sh_skip_prologue (CORE_ADDR start_pc)
   return pc;
 }
 
-/* Should call_function allocate stack space for a struct return?  */
+/* Should call_function allocate stack space for a struct return?
+
+   The ABI says:
+
+   Aggregate types not bigger than 8 bytes that have the same size and
+   alignment as one of the integer scalar types are returned in the
+   same registers as the integer type they match.
+
+   For example, a 2-byte aligned structure with size 2 bytes has the
+   same size and alignment as a short int, and will be returned in R0.
+   A 4-byte aligned structure with size 8 bytes has the same size and
+   alignment as a long long int, and will be returned in R0 and R1.
+
+   When an aggregate type is returned in R0 and R1, R0 contains the
+   first four bytes of the aggregate, and R1 contains the
+   remainder. If the size of the aggregate type is not a multiple of 4
+   bytes, the aggregate is tail-padded up to a multiple of 4
+   bytes. The value of the padding is undefined. For little-endian
+   targets the padding will appear at the most significant end of the
+   last element, for big-endian targets the padding appears at the
+   least significant end of the last element.
+
+   All other aggregate types are returned by address. The caller
+   function passes the address of an area large enough to hold the
+   aggregate value in R2. The called function stores the result in
+   this location."
+
+   To reiterate, structs smaller than 8 bytes could also be returned
+   in memory, if they don't pass the "same size and alignment as an
+   integer type" rule.
+
+   For example, in
+
+   struct s { char c[3]; } wibble;
+   struct s foo(void) {  return wibble; }
+
+   the return value from foo() will be in memory, not
+   in R0, because there is no 3-byte integer type.
+
+*/
+
 static int
 sh_use_struct_convention (int gcc_p, struct type *type)
 {