From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 30222 invoked by alias); 15 Sep 2007 09:52:29 -0000 Received: (qmail 30208 invoked by uid 22791); 15 Sep 2007 09:52:27 -0000 X-Spam-Check-By: sourceware.org Received: from romy.inter.net.il (HELO romy.inter.net.il) (213.8.233.24) by sourceware.org (qpsmtpd/0.31) with ESMTP; Sat, 15 Sep 2007 09:52:22 +0000 Received: from HOME-C4E4A596F7 (IGLD-80-230-210-74.inter.net.il [80.230.210.74]) by romy.inter.net.il (MOS 3.7.3-GA) with ESMTP id IWT55431 (AUTH halo1); Sat, 15 Sep 2007 12:51:41 +0300 (IDT) Date: Sat, 15 Sep 2007 09:52:00 -0000 Message-Id: From: Eli Zaretskii To: Roland McGrath CC: jan.kratochvil@redhat.com, gdb-patches@sourceware.org In-reply-to: <20070904072130.089B04D04CC@magilla.localdomain> (message from Roland McGrath on Tue, 4 Sep 2007 00:21:29 -0700 (PDT)) Subject: Re: [patch] build-id .debug files load (like .gnu_debuglink) Reply-to: Eli Zaretskii References: <20070904072130.089B04D04CC@magilla.localdomain> X-IsSubscribed: yes Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2007-09/txt/msg00187.txt.bz2 > From: Roland McGrath > Cc: jan.kratochvil@redhat.com, gdb-patches@sourceware.org > Date: Tue, 4 Sep 2007 00:21:29 -0700 (PDT) > > > > It is also not good to use the term "signature" loosely with relation to > > > build ID bits. > > > > What alternative term would you suggest? I have no shares in this > > particular word, if a good alternative exists. > > Well, there is "ID". Also "bit string", or "set of bits", or "sequence of > bytes" come to mind. Whatever flows in the particular context to say what > is so, which is that it is a small chunk of data taken solely as an > identifier with no instrinsic meaning to its bits. The text I wrote in the > ld manual (ld/ld.texinfo @node Options) uses "unique bits" and "bit string". > > Also, I don't think it is proper to refer to this as GNU/Linux operating > system magic and refer to the Fedora wiki. The build ID note is a GNU > convention for ELF binaries and the tool involved in creating it is GNU ld. > It is the linker, and how the linker is used, that determines whether > creating a binary normally gives it one. The GDB manual should refer > directly to the GNU ld manual about how it's created. > > If you mean the manual to document precise format details, then it should > not say that a build ID section is "named @code{.note.gnu.build-id}". That > is the name of the input section that ld synthesizes under --build-id, and > will often be the name of the final section seen in an executable or DSO. > But the name is in no way magical and any tool would be broken if it worked > only on a section by that name. It should be mentioned only as a common > case. It is only the normative ELF data that controls what constitutes a > proper build ID in an ELF file. That is, SHT_NOTE sections, or PT_NOTE > segments in sectionless files, with proper ELF note formats of name "GNU" > and type NT_GNU_BUILD_ID. > > The wording now says "executable" a lot, while in reality it can be any > kind of ELF file that gdb would consider. That is, executables or DSOs > (ET_EXEC/ET_DYN), or ET_REL files that are contemplated in their own right, > as is done for Linux kernel modules. For all of these, gdb can find > separate debug info, and should use build IDs to do so. Thanks for your comments and explanations. I believe I've fixed the manual according to your suggestions, the patch I committed is attached below. 2007-09-15 Eli Zaretskii * gdb.texinfo (Separate Debug Files): More accurate wording regarding build ID and a reference to the ld manual rather than the Fedora wiki. Index: gdb.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v retrieving revision 1.430 diff -u -r1.430 gdb.texinfo --- gdb.texinfo 15 Sep 2007 08:54:26 -0000 1.430 +++ gdb.texinfo 15 Sep 2007 09:48:18 -0000 @@ -11933,14 +11933,15 @@ came from the same build. @item -The executable contains a @dfn{build ID}, a unique signature that is +The executable contains a @dfn{build ID}, a unique bit string that is also present in the corresponding debug info file. (This is supported -only on some operating systems, notably on @sc{gnu}/Linux. For more -details about this feature, see -@uref{http://fedoraproject.org/wiki/Releases/FeatureBuildId, the -Fedora Project's description of the buid ID feature}.) The debug info -file's name is not specified explicitly by the build ID, but can be -computed from the build ID, see below. +only on some operating systems, notably those which use the ELF format +for binary files and the @sc{gnu} Binutils.) For more details about +this feature, see the description of the @option{--build-id} +command-line option in @ref{Options, , Command Line Options, ld.info, +The GNU Linker}. The debug info file's name is not specified +explicitly by the build ID, but can be computed from the build ID, see +below. @end itemize Depending on the way the debug info file is specified, @value{GDBN} @@ -11958,14 +11959,14 @@ For the ``build ID'' method, @value{GDBN} looks in the @file{.build-id} subdirectory of the global debug directory for a file named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the -first 2 hex characters of the build ID signature, and @var{nnnnnnnn} -are the rest of the signature. (Real signatures are 32 or more -characters, not 10.) +first 2 hex characters of the build ID bit string, and @var{nnnnnnnn} +are the rest of the bit string. (Real build ID strings are 32 or more +hex characters, not 10.) @end itemize So, for example, suppose you ask @value{GDBN} to debug -@file{/usr/bin/ls}, which has a @dfn{debug link} that specifies the -file @file{ls.debug}, and a @dfn{build id} whose value in hex is +@file{/usr/bin/ls}, which has a debug link that specifies the +file @file{ls.debug}, and a build ID whose value in hex is @code{abcdef1234}. If the global debug directory is @file{/usr/lib/debug}, then @value{GDBN} will look for the following debug information files, in the indicated order: @@ -12023,14 +12024,15 @@ @cindex @code{.note.gnu.build-id} sections @cindex build ID sections -A build ID is a special section of the executable file named -@code{.note.gnu.build-id}. This section contains unique -identification for the built files---it remains the same across -multiple builds of the same build tree. The default algorithm SHA1 -produces 160 bits (40 hexadecimal characters) of the content. The -same section with an identical value is present in the original built -binary with symbols, in its stripped variant, and in the separate -debugging information file. +The build ID is a special section in the executable file (and in other +ELF binary files that @value{GDBN} may consider). This section is +often named @code{.note.gnu.build-id}, but that name is not mandatory. +It contains unique identification for the built files---the ID remains +the same across multiple builds of the same build tree. The default +algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the +content for the build ID string. The same section with an identical +value is present in the original built binary with symbols, in its +stripped variant, and in the separate debugging information file. The debugging information file itself should be an ordinary executable, containing a full set of linker symbols, sections, and @@ -12039,7 +12041,7 @@ but they need not contain any data---much like a @code{.bss} section in an ordinary executable. -@sc{gnu} binary utilities (Binutils) package includes the +The @sc{gnu} binary utilities (Binutils) package includes the @samp{objcopy} utility that can produce the separated executable / debugging information file pairs using the following commands: @@ -12073,7 +12075,7 @@ Build ID gets embedded into the main executable using @code{ld --build-id} or the @value{NGCC} counterpart @code{gcc -Wl,--build-id}. Build ID support plus compatibility fixes for debug files separation are present in @sc{gnu} binary -utilities (Binutils) since version 2.18. +utilities (Binutils) package since version 2.18. @end itemize @noindent