[SCM] archer-gbenson-stap-rtld: Document the new stuff

[SCM] archer-gbenson-stap-rtld: Document the new stuff

[gary]

The branch, archer-gbenson-stap-rtld has been updated
       via  ef5485e2bda764bf857e364521b4a05e4dbd55cc (commit)
      from  fed2e75a9cfe778535f99415ff4e3bdb1c9870d0 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email.

- Log -----------------------------------------------------------------
commit ef5485e2bda764bf857e364521b4a05e4dbd55cc
Author: Gary Benson <gbenson@redhat.com>
Date:   Fri Jun 3 10:55:19 2011 +0100

    Document the new stuff

-----------------------------------------------------------------------

Summary of changes:
 gdb/solib-svr4.c |   18 ++++++++++++++----
 gdb/solib.c      |    2 +-
 gdb/solib.h      |    2 +-
 gdb/solist.h     |    6 +++++-
 4 files changed, 21 insertions(+), 7 deletions(-)

First 500 lines of diff:
diff --git a/gdb/solib-svr4.c b/gdb/solib-svr4.c
index 6caf22b..d945ff2 100644
--- a/gdb/solib-svr4.c
+++ b/gdb/solib-svr4.c
@@ -1318,7 +1318,7 @@ exec_entry_point (struct bfd *abfd, struct target_ops *targ)
 					     targ);
 }
 
-/* XXX document  */
+/* Helper function for svr4_update_solib_event_breakpoints.  */
 
 static int
 svr4_update_solib_event_breakpoint (struct breakpoint *b, void *arg)
@@ -1334,7 +1334,8 @@ svr4_update_solib_event_breakpoint (struct breakpoint *b, void *arg)
   return 0;
 }
 
-/* XXX document  */
+/* Enable or disable optional solib event breakpoints as appropriate.
+   Called whenever stop_on_solib_events is changed.  */
 
 static void
 svr4_update_solib_event_breakpoints (void)
@@ -1342,7 +1343,17 @@ svr4_update_solib_event_breakpoints (void)
   iterate_over_breakpoints (svr4_update_solib_event_breakpoint, NULL);
 }
 
-/* XXX document  */
+/* Both the SunOS and the SVR4 dynamic linkers call a marker function
+   before and after mapping and unmapping shared libraries.  The sole
+   purpose of this method is to allow debuggers to set a breakpoint so
+   they can track these changes.
+
+   Some versions of the glibc dynamic linker contain SystemTap probes
+   to allow more fine grained stopping.  Given the address of the
+   original marker function, this function attempts to find these
+   probes, and if found, sets breakpoints on those instead.  If the
+   probes aren't found, a single breakpoint is set on the original
+   SVR4 marker function.  */
 
 static void
 svr4_create_solib_event_breakpoints (struct gdbarch *gdbarch, CORE_ADDR address)
@@ -1373,7 +1384,6 @@ svr4_create_solib_event_breakpoints (struct gdbarch *gdbarch, CORE_ADDR address)
 	     map has been changed.  We always need to break on this
 	     one so we can track libraries being loaded and
 	     unloaded.  */
-	  /* XXX really?  */
 	  create_solib_event_breakpoint (gdbarch,
 					 info->post_mod_probe->address);
 	  
diff --git a/gdb/solib.c b/gdb/solib.c
index 4c4bb59..129724d 100644
--- a/gdb/solib.c
+++ b/gdb/solib.c
@@ -1309,7 +1309,7 @@ no_shared_libraries (char *ignored, int from_tty)
   objfile_purge_solibs ();
 }
 
-/* XXX document.  */
+/* Enable or disable optional solib event breakpoints as appropriate.  */
 
 void
 update_solib_breakpoints (void)
diff --git a/gdb/solib.h b/gdb/solib.h
index f73e4b1..7b3881c 100644
--- a/gdb/solib.h
+++ b/gdb/solib.h
@@ -78,7 +78,7 @@ extern void set_solib_ops (struct gdbarch *gdbarch,
 
 extern int libpthread_name_p (const char *name);
 
-/* XXX document.  */
+/* Enable or disable optional solib event breakpoints as appropriate.  */
 
 extern void update_solib_breakpoints (void);
 
diff --git a/gdb/solist.h b/gdb/solist.h
index dac28e9..14ede10 100644
--- a/gdb/solist.h
+++ b/gdb/solist.h
@@ -138,7 +138,11 @@ struct target_so_ops
     int (*keep_data_in_core) (CORE_ADDR vaddr,
 			      unsigned long size);
 
-    /* XXX document.  */
+    /* Enable or disable optional solib event breakpoints as
+       appropriate.  This should be called whenever
+       stop_on_solib_events is changed.  This pointer can be
+       NULL, in which case no enabling or disabling is necessary
+       for this target.  */
     void (*update_breakpoints) (void);
   };
 


hooks/post-receive
--
Repository for Project Archer.