[src/trunk]: src/include Refine the documentation of r_debug

[kamil <kamil%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/60ffe593f72d
branches:  trunk
changeset: 938938:60ffe593f72d
user:      kamil <kamil%NetBSD.org@localhost>
date:      Mon Sep 21 02:20:27 2020 +0000

description:
Refine the documentation of r_debug

Obtained from OpenBSD link.h r.1.15.

diffstat:

 include/link_elf.h |  20 +++++++++++++++++---
 1 files changed, 17 insertions(+), 3 deletions(-)

diffs (39 lines):

diff -r f512f5522fa8 -r 60ffe593f72d include/link_elf.h
--- a/include/link_elf.h        Sun Sep 20 23:48:09 2020 +0000
+++ b/include/link_elf.h        Mon Sep 21 02:20:27 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: link_elf.h,v 1.10 2010/10/16 10:27:06 skrll Exp $      */
+/*     $NetBSD: link_elf.h,v 1.11 2020/09/21 02:20:27 kamil Exp $      */
 
 #ifndef _LINK_ELF_H_
 #define        _LINK_ELF_H_
@@ -18,13 +18,27 @@
 } Link_map;
 
 /*
- * This only exists for GDB.
+ * Debug rendezvous struct. Pointer to this is set up in the
+ * target code pointed by the DT_DEBUG tag. If it is
+ * defined.
  */
 struct r_debug {
-       int r_version;                  /* not used */
+       int r_version;                  /* protocol version */
        struct link_map *r_map;         /* list of loaded images */
+
+       /*
+        * This is the address of a function internal to the run-time linker,
+        * that will always be called when the linker begins to map in a
+        * library or unmap it, and again when the mapping change is complete.
+        * The debugger can set a breakpoint at this address if it wants to
+        * notice shared object mapping changes.
+        */
        void (*r_brk)(void);            /* pointer to break point */
        enum {
+               /*
+                * This state value describes the mapping change taking place
+                * when the `r_brk' address is called.
+                */
                RT_CONSISTENT,          /* things are stable */
                RT_ADD,                 /* adding a shared library */
                RT_DELETE               /* removing a shared library */