[RFC] Document replacement for frame_register_read (deprecated).

[Joel Brobecker <brobecker@adacore.com>]

Hello,

This is inspired by a discussion from a long time ago:
http://www.sourceware.org/ml/gdb-patches/2011-03/msg01095.html

If you agree with the patch, we will also have to update the ARI
script to mention get_frame_register_value as the alternative.

And we might also want to rename the function as well. I don't think
we can rely on the ARI alone to avoid new uses of this function.
And once new uses are in, it's much harder to make sure we undo them.

Thoughts?

gdb/ChangeLog:

        * frame.h (frame_register_read): Remove FIXME comment.
        * frame.c (frame_register_read): Add suggestion explaining
        which function to use in place of this one.

Thanks,
-- 
Joel


---
 gdb/frame.c |    3 ++-
 gdb/frame.h |   12 ------------
 2 files changed, 2 insertions(+), 13 deletions(-)

diff --git a/gdb/frame.c b/gdb/frame.c
index a2f23a4..ea0cb90 100644
--- a/gdb/frame.c
+++ b/gdb/frame.c
@@ -1093,7 +1093,8 @@ put_frame_register (struct frame_info *frame, int regnum,
     }
 }
 
-/* frame_register_read ()
+/* This function is deprecated.  Use get_frame_register_value instead,
+   which provides more accurate information.
 
    Find and return the value of REGNUM for the specified stack frame.
    The number of bytes copied is REGISTER_SIZE (REGNUM).
diff --git a/gdb/frame.h b/gdb/frame.h
index fa80663..c0559d9 100644
--- a/gdb/frame.h
+++ b/gdb/frame.h
@@ -673,18 +673,6 @@ extern struct frame_info *block_innermost_frame (const struct block *);
 
 extern int deprecated_pc_in_call_dummy (struct gdbarch *gdbarch, CORE_ADDR pc);
 
-/* FIXME: cagney/2003-02-02: Should be deprecated or replaced with a
-   function called get_frame_register_p().  This slightly weird (and
-   older) variant of get_frame_register() returns zero (indicating the
-   register value is unavailable/invalid) if either: the register
-   isn't cached; or the register has been optimized out; or the
-   register contents are unavailable (because they haven't been
-   collected in a traceframe).  Problem is, neither check is exactly
-   correct.  A register can't be optimized out (it may not have been
-   saved as part of a function call); The fact that a register isn't
-   in the register cache doesn't mean that the register isn't
-   available (it could have been fetched from memory).  */
-
 extern int frame_register_read (struct frame_info *frame, int regnum,
 				gdb_byte *buf);
 
-- 
1.7.9.5