Blame elf/rtld-debugger-interface.txt

Packit Service 82fcde
Standard debugger interface
Packit Service 82fcde
===========================
Packit Service 82fcde
Packit Service 82fcde
The run-time linker exposes a rendezvous structure to allow debuggers
Packit Service 82fcde
to interface with it.  This structure, r_debug, is defined in link.h.
Packit Service 82fcde
If the executable's dynamic section has a DT_DEBUG element, the
Packit Service 82fcde
run-time linker sets that element's value to the address where this
Packit Service 82fcde
structure can be found.
Packit Service 82fcde
Packit Service 82fcde
The r_debug structure contains (amongst others) the following fields:
Packit Service 82fcde
Packit Service 82fcde
  struct link_map *r_map:
Packit Service 82fcde
    A linked list of loaded objects.
Packit Service 82fcde
Packit Service 82fcde
  enum { RT_CONSISTENT, RT_ADD, RT_DELETE } r_state:
Packit Service 82fcde
    The current state of the r_map list.  RT_CONSISTENT means that r_map
Packit Service 82fcde
    is not currently being modified and may safely be inspected.  RT_ADD
Packit Service 82fcde
    means that an object is being added to r_map, and that the list is
Packit Service 82fcde
    not guaranteed to be consistent.  Likewise RT_DELETE means that an
Packit Service 82fcde
    object is being removed from the list.
Packit Service 82fcde
Packit Service 82fcde
  ElfW(Addr) r_brk:
Packit Service 82fcde
    The address of a function internal to the run-time linker which is
Packit Service 82fcde
    called whenever r_state is changed.  The debugger should set a
Packit Service 82fcde
    breakpoint at this address if it wants to notice mapping changes.
Packit Service 82fcde
Packit Service 82fcde
This protocol is widely supported, but somewhat limited in that it
Packit Service 82fcde
has no provision to provide access to multiple namespaces, and that
Packit Service 82fcde
the notifications (via r_brk) only refer to changes to r_map--the
Packit Service 82fcde
debugger is notified that a new object has been added, for instance,
Packit Service 82fcde
but there is no way for the debugger to discover whether any of the
Packit Service 82fcde
objects in the link-map have been relocated or not.
Packit Service 82fcde
Packit Service 82fcde
Packit Service 82fcde
Probe-based debugger interface
Packit Service 82fcde
==============================
Packit Service 82fcde
Packit Service 82fcde
Systemtap is a dynamic tracing/instrumenting tool available on Linux.
Packit Service 82fcde
Probes that are not fired at run time have close to zero overhead.
Packit Service 82fcde
glibc contains a number of probes that debuggers can set breakpoints
Packit Service 82fcde
on in order to notice certain events.
Packit Service 82fcde
Packit Service 82fcde
All rtld probes have the following arguments:
Packit Service 82fcde
Packit Service 82fcde
  arg1: Lmid_t lmid:
Packit Service 82fcde
    The link-map ID of the link-map list that the object was loaded
Packit Service 82fcde
    into.  This will be LM_ID_BASE for the application's main link-map
Packit Service 82fcde
    list, or some other value for different namespaces.
Packit Service 82fcde
Packit Service 82fcde
  arg2: struct r_debug *r_debug:
Packit Service 82fcde
    A pointer to the r_debug structure containing the link-map list
Packit Service 82fcde
    that the object was loaded into.  This will be the value stored in
Packit Service 82fcde
    DT_DEBUG for the application's main link-map list, or some other
Packit Service 82fcde
    value for different namespaces.
Packit Service 82fcde
Packit Service 82fcde
map_complete and reloc_complete may have the following additional
Packit Service 82fcde
argument:
Packit Service 82fcde
Packit Service 82fcde
  arg3: struct link_map *new:
Packit Service 82fcde
    A pointer which, if not NULL, points to the entry in the specified
Packit Service 82fcde
    r_debug structure's link-map list corresponding to the first new
Packit Service 82fcde
    object to have been mapped or relocated, with new->l_next pointing
Packit Service 82fcde
    to the link-map of the next new object to have been mapped or
Packit Service 82fcde
    relocated, and so on.  Note that because `new' is an entry in a
Packit Service 82fcde
    larger list, new->l_prev (if not NULL) will point to what was the
Packit Service 82fcde
    last link-map in the link-map list prior to the new objects being
Packit Service 82fcde
    mapped or relocated.
Packit Service 82fcde
Packit Service 82fcde
The following probes are available:
Packit Service 82fcde
Packit Service 82fcde
  init_start:
Packit Service 82fcde
    This is called once, when the linker is about to fill in the main
Packit Service 82fcde
    r_debug structure at application startup.  init_start always has
Packit Service 82fcde
    lmid set to LM_ID_BASE and r_debug set to the value stored in
Packit Service 82fcde
    DT_DEBUG.  r_debug is not guaranteed to be consistent until
Packit Service 82fcde
    init_complete is fired.
Packit Service 82fcde
Packit Service 82fcde
  init_complete:
Packit Service 82fcde
    This is called once, when the linker has filled in the main
Packit Service 82fcde
    r_debug structure at application startup. init_complete always
Packit Service 82fcde
    has lmid set to LM_ID_BASE and r_debug set to the value stored
Packit Service 82fcde
    in DT_DEBUG.  The r_debug structure is consistent and may be
Packit Service 82fcde
    inspected, and all objects in the link-map are guaranteed to
Packit Service 82fcde
    have been relocated.
Packit Service 82fcde
Packit Service 82fcde
  map_start:
Packit Service 82fcde
    The linker is about to map new objects into the specified
Packit Service 82fcde
    namespace.  The namespace's r_debug structure is not guaranteed
Packit Service 82fcde
    to be consistent until a corresponding map_complete is fired.
Packit Service 82fcde
Packit Service 82fcde
  map_complete:
Packit Service 82fcde
    The linker has finished mapping new objects into the specified
Packit Service 82fcde
    namespace.  The namespace's r_debug structure is consistent and
Packit Service 82fcde
    may be inspected, although objects in the namespace's link-map
Packit Service 82fcde
    are not guaranteed to have been relocated.
Packit Service 82fcde
Packit Service 82fcde
  map_failed:
Packit Service 82fcde
    The linker failed while attempting to map new objects into
Packit Service 82fcde
    the specified namespace.  The namespace's r_debug structure
Packit Service 82fcde
    is consistent and may be inspected.
Packit Service 82fcde
Packit Service 82fcde
  reloc_start:
Packit Service 82fcde
    The linker is about to relocate all unrelocated objects in the
Packit Service 82fcde
    specified namespace.  The namespace's r_debug structure is not
Packit Service 82fcde
    guaranteed to be consistent until a corresponding reloc_complete
Packit Service 82fcde
    is fired.
Packit Service 82fcde
Packit Service 82fcde
  reloc_complete:
Packit Service 82fcde
    The linker has relocated all objects in the specified namespace.
Packit Service 82fcde
    The namespace's r_debug structure is consistent and may be
Packit Service 82fcde
    inspected, and all objects in the namespace's link-map are
Packit Service 82fcde
    guaranteed to have been relocated.
Packit Service 82fcde
Packit Service 82fcde
  unmap_start:
Packit Service 82fcde
    The linker is about to remove objects from the specified
Packit Service 82fcde
    namespace.  The namespace's r_debug structure is not guaranteed to
Packit Service 82fcde
    be consistent until a corresponding unmap_complete is fired.
Packit Service 82fcde
Packit Service 82fcde
  unmap_complete:
Packit Service 82fcde
    The linker has finished removing objects into the specified
Packit Service 82fcde
    namespace.  The namespace's r_debug structure is consistent and
Packit Service 82fcde
    may be inspected.