[patch] describe some frame unwinder functions

[patch] describe some frame unwinder functions

[Thiago Jung Bauermann]

[-- Attachment #1: Type: text/plain, Size: 259 bytes --]

Hi,

This patch adds explanations to some functions in the frame unwinder. I
think they're very helpful (albeit somewhat concise), assuming I got
them right. :-)

What do you think?
-- 
[]'s
Thiago Jung Bauermann
Software Engineer
IBM Linux Technology Center

[-- Attachment #2: frame-unwinder-comments.patch --]
[-- Type: text/x-patch, Size: 1798 bytes --]

2007-09-23  Thiago Jung Bauermann  <bauerman@br.ibm.com>

	* frame.c (frame_pc_unwind): Add purpose explanation.
	(frame_func_unwind): Likewise.
	(frame_register_unwind): Likewise.
	(get_frame_pc): Likewise.

Index: src-git/gdb/frame.c
===================================================================
--- src-git.orig/gdb/frame.c	2007-09-14 18:45:28.000000000 -0300
+++ src-git/gdb/frame.c	2007-09-23 18:46:21.000000000 -0300
@@ -421,6 +421,8 @@ frame_find_by_id (struct frame_id id)
   return NULL;
 }
 
+/* Return the PC value at the time the caller of this frame was active.  */
+
 CORE_ADDR
 frame_pc_unwind (struct frame_info *this_frame)
 {
@@ -468,6 +470,9 @@ frame_pc_unwind (struct frame_info *this
   return this_frame->prev_pc.value;
 }
 
+/* Return the address of the first instruction in the function which
+ * called frame FI.  */
+
 CORE_ADDR
 frame_func_unwind (struct frame_info *fi, enum frame_type this_type)
 {
@@ -547,6 +552,16 @@ frame_pop (struct frame_info *this_frame
   reinit_frame_cache ();
 }
 
+/* Obtain value of REGNUM at the time FRAME was active.
+ *
+ * *OPTIMIZEDP is set to 1 if register value cannot be obtained.
+ * *LVALP is set to location in inferior where the value is saved.
+ * If it is saved in inferior memory, *ADDRP is set to its address.
+ * If it is saved in another register, *REALNUMP is set to the new
+ * register number.
+ *
+ * If BUFFERP is not NULL, save register value to *BUFFERP.  */
+
 void
 frame_register_unwind (struct frame_info *frame, int regnum,
 		       int *optimizedp, enum lval_type *lvalp,
@@ -1485,6 +1500,8 @@ get_prev_frame (struct frame_info *this_
   return get_prev_frame_1 (this_frame);
 }
 
+/* Return the PC value at the time this frame was active.  */
+
 CORE_ADDR
 get_frame_pc (struct frame_info *frame)
 {

Re: [patch] describe some frame unwinder functions

[Jim Blandy]

Thiago Jung Bauermann <bauerman@br.ibm.com> writes:
> This patch adds explanations to some functions in the frame unwinder. I
> think they're very helpful (albeit somewhat concise), assuming I got
> them right. :-)

These functions all have comments where they're declared in frame.h.
I think it would be best to fix those if they're not clear; I don't
think we should repeat function head comments in both places.

There seem to be two schools regarding comments.  One says to put them
in header files, becase a module's .h file is its interface, and
that's where people should go to see how to use it.  The other says to
put them directly above the functions, because that's where the actual
code is.

GDB sort of does both, or neither, depending on the age and original
author of the code.

The Subversion project's coding standard followed the header file
approach, with the requirement that the comments had to be good enough
to use the functions without reading their code, in most cases.  Where
that standard is in force, I think header files are the right place.
For example, prologue-value.h, macrotab.h, and macroexp.h all work
fine this way.

For some parts of GDB, the real-life behaviors of the functions
themselves are hairy enough that it may be unrealistic to ever expect
anyone to use them without reading their code.