elf: Add _dl_find_object function

It can be used to speed up the libgcc unwinder, and the internal
_dl_find_dso_for_object function (which is used for caller
identification in dlopen and related functions, and in dladdr).

_dl_find_object is in the internal namespace due to bug 28503.
If libgcc switches to _dl_find_object, this namespace issue will
be fixed.  It is located in libc for two reasons: it is necessary
to forward the call to the static libc after static dlopen, and
there is a link ordering issue with -static-libgcc and libgcc_eh.a
because libc.so is not a linker script that includes ld.so in the
glibc build tree (so that GCC's internal -lc after libgcc_eh.a does
not pick up ld.so).

It is necessary to do the i386 customization in the
sysdeps/x86/bits/dl_find_object.h header shared with x86-64 because
otherwise, multilib installations are broken.

The implementation uses software transactional memory, as suggested
by Torvald Riegel.  Two copies of the supporting data structures are
used, also achieving full async-signal-safety.

Reviewed-by: Adhemerval Zanella  <adhemerval.zanella@linaro.org>

5 files changed, 140 insertions, 13 deletions

diff --git a/manual/Makefile b/manual/Makefile
index e83444341e..31678681ef 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -39,7 +39,7 @@ chapters = $(addsuffix .texi, \
 		       pipe socket terminal syslog math arith time	\
 		       resource setjmp signal startup process ipc job	\
 		       nss users sysinfo conf crypt debug threads	\
-		       probes tunables)
+		       dynlink probes tunables)
 appendices = lang.texi header.texi install.texi maint.texi platform.texi \
 	     contrib.texi
 licenses = freemanuals.texi lgpl-2.1.texi fdl-1.3.texi
diff --git a/manual/dynlink.texi b/manual/dynlink.texi
new file mode 100644
index 0000000000..54091be18e
--- /dev/null
+++ b/manual/dynlink.texi
@@ -0,0 +1,137 @@
+@node Dynamic Linker
+@c @node Dynamic Linker, Internal Probes, Threads, Top
+@c %MENU% Loading programs and shared objects.
+@chapter Dynamic Linker
+@cindex dynamic linker
+@cindex dynamic loader
+
+The @dfn{dynamic linker} is responsible for loading dynamically linked
+programs and their dependencies (in the form of shared objects).  The
+dynamic linker in @theglibc{} also supports loading shared objects (such
+as plugins) later at run time.
+
+Dynamic linkers are sometimes called @dfn{dynamic loaders}.
+
+@menu
+* Dynamic Linker Introspection::    Interfaces for querying mapping information.
+@end menu
+
+@node Dynamic Linker Introspection
+@section Dynamic Linker Introspection
+
+@Theglibc{} provides various functions for querying information from the
+dynamic linker.
+
+@deftp {Data Type} {struct dl_find_object}
+@standards{GNU, dlfcn.h}
+This structure contains information about a main program or loaded
+object.  The @code{_dl_find_object} function uses it to return
+result data to the caller.
+
+@table @code
+@item unsigned long long int dlfo_flags
+Currently unused and always 0.
+
+@item void *dlfo_map_start
+The start address of the inspected mapping.  This information comes from
+the program header, so it follows its convention, and the address is not
+necessarily page-aligned.
+
+@item void *dlfo_map_end
+The end address of the mapping.
+
+@item struct link_map *dlf_link_map
+This member contains a pointer to the link map of the object.
+
+@item struct link_map *dlf_link_map
+This member contains a pointer to the exception handling data of the
+object.  See @code{DLFO_EH_SEGMENT_TYPE} below.
+
+@end table
+
+This structure is a GNU extension.
+@end deftp
+
+@deftypevr Macro int DLFO_STRUCT_HAS_EH_DBASE
+@standards{GNU, dlfcn.h}
+On most targets, this macro is defined as @code{0}.  If it is defined to
+@code{1}, @code{struct dl_find_object} contains an additional member
+@code{dlfo_eh_dbase} of type @code{void *}.  It is the base address for
+@code{DW_EH_PE_datarel} DWARF encodings to this location.
+
+This macro is a GNU extension.
+@end deftypevr
+
+@deftypevr Macro int DLFO_STRUCT_HAS_EH_COUNT
+@standards{GNU, dlfcn.h}
+On most targets, this macro is defined as @code{0}.  If it is defined to
+@code{1}, @code{struct dl_find_object} contains an additional member
+@code{dlfo_eh_count} of type @code{int}.  It is the number of exception
+handling entries in the EH frame segment identified by the
+@code{dlfo_eh_frame} member.
+
+This macro is a GNU extension.
+@end deftypevr
+
+@deftypevr Macro int DLFO_EH_SEGMENT_TYPE
+@standards{GNU, dlfcn.h}
+On targets using DWARF-based exception unwinding, this macro expands to
+@code{PT_GNU_EH_FRAME}.  This indicates that @code{dlfo_eh_frame} in
+@code{struct dl_find_object} points to the @code{PT_GNU_EH_FRAME}
+segment of the object.  On targets that use other unwinding formats, the
+macro expands to the program header type for the unwinding data.
+
+This macro is a GNU extension.
+@end deftypevr
+
+@deftypefun {int} _dl_find_object (void *@var{address}, struct dl_find_object *@var{result})
+@standards{GNU, dlfcn.h}
+@safety{@mtsafe{}@assafe{}@acsafe{}}
+On success, this function returns 0 and writes about the object
+surrounding the address to @code{*@var{result}}.  On failure, -1 is
+returned.
+
+The @var{address} can be a code address or data address.  On
+architectures using function descriptors, no attempt is made to decode
+the function descriptor.  Depending on how these descriptors are
+implemented, @code{_dl_find_object} may return the object that defines
+the function descriptor (and not the object that contains the code
+implementing the function), or fail to find any object at all.
+
+On success @var{address} is greater than or equal to
+@code{@var{result}->dlfo_map_start} and less than
+@code{@var{result}->dlfo_map_end}, that is, the supplied code address is
+located within the reported mapping.
+
+This function returns a pointer to the unwinding information for the
+object that contains the program code @var{address} in
+@code{@var{result}->dlfo_eh_frame}.  If the platform uses DWARF
+unwinding information, this is the in-memory address of the
+@code{PT_GNU_EH_FRAME} segment.  See @code{DLFO_EH_SEGMENT_TYPE} above.
+In case @var{address} resides in an object that lacks unwinding information,
+the function still returns 0, but sets @code{@var{result}->dlfo_eh_frame}
+to a null pointer.
+
+@code{_dl_find_object} itself is thread-safe.  However, if the
+application invokes @code{dlclose} for the object that contains
+@var{address} concurrently with @code{_dl_find_object} or after the call
+returns, accessing the unwinding data for that object or the link map
+(through @code{@var{result}->dlfo_link_map}) is not safe.  Therefore, the
+application needs to ensure by other means (e.g., by convention) that
+@var{address} remains a valid code address while the unwinding
+information is processed.
+
+This function is a GNU extension.
+@end deftypefun
+
+
+@c FIXME these are undocumented:
+@c dladdr
+@c dladdr1
+@c dlclose
+@c dlerror
+@c dlinfo
+@c dlmopen
+@c dlopen
+@c dlsym
+@c dlvsym
diff --git a/manual/libdl.texi b/manual/libdl.texi
deleted file mode 100644
index e3fe0452d9..0000000000
--- a/manual/libdl.texi
+++ /dev/null
@@ -1,10 +0,0 @@
-@c FIXME these are undocumented:
-@c dladdr
-@c dladdr1
-@c dlclose
-@c dlerror
-@c dlinfo
-@c dlmopen
-@c dlopen
-@c dlsym
-@c dlvsym
diff --git a/manual/probes.texi b/manual/probes.texi
index 4aae76b819..ee019e6517 100644
--- a/manual/probes.texi
+++ b/manual/probes.texi
@@ -1,5 +1,5 @@
 @node Internal Probes
-@c @node Internal Probes, Tunables, Threads, Top
+@c @node Internal Probes, Tunables, Dynamic Linker, Top
 @c %MENU% Probes to monitor libc internal behavior
 @chapter Internal probes
 
diff --git a/manual/threads.texi b/manual/threads.texi
index ab44a92ca0..4869f69d2c 100644
--- a/manual/threads.texi
+++ b/manual/threads.texi
@@ -1,5 +1,5 @@
 @node Threads
-@c @node Threads, Internal Probes, Debugging Support, Top
+@c @node Threads, Dynamic Linker, Debugging Support, Top
 @c %MENU% Functions, constants, and data types for working with threads
 @chapter Threads
 @cindex threads