Re: [RFA] Add stabs entries for coalesced symbols.

[Klee Dienes <klee@apple.com>]

[-- Attachment #1: Type: text/plain, Size: 3202 bytes --]

[ I should first warn you that I'm by no means an authority on our 
implementation of coalesced symbols; my only real experience with them 
is teaching GDB to ignore them. ]


On Tuesday, November 19, 2002, at 01:23 AM, Ian Lance Taylor wrote:

> Coalesced symbols look quite similar to COMDAT sections (e.g.,
> SEC_LINK_DUPLICATES_DISCARD).  They're called coalesced *symbols*, but
> in BFD terminology they are really *sections*.  It would be nice if
> you mentioned this in your new documentation.  Thanks.

My understanding is that coalesced symbols are similar to, but not 
quite the same as COMDAT sections.  In our implementation, coalesced 
symbols are placed into sections marked with the S_COALESCED flag, each 
of which may contain any number of coalesced symbols.  I've tried to 
make the documentation reflect this a bit better (speaking of which, I 
should mention that these docs are extensively plagiarized from docs 
written by another engineer at Apple; I'm just adapting them as best I 
can from the release notes for use in the stabs document).

Are you saying that our BFD Mach-O layer should be mapping each symbol 
in a Mach-O coalesced section into a separate BFD section flagged with 
SEC_LINK_DUPLICATES_DISCARD?  Unfortunately, we haven't yet extended 
our BFD layer to anything beyond that needed to support GDB and 
objdump/objcopy/etc., but it would be nice to know how to proceed for 
future reference.


On Tuesday, November 19, 2002, at 01:59 AM, Eli Zaretskii wrote:

> Also, are coalesced symbols a MacOS-only feature, or are they supported
> (or can reasonably be expected to be supported in the future) on other
> platforms?  If the former, I think we should tell right at the start of
> this section that the information pertains only to the Mac.

There's no reason they couldn't be supported on other platforms, though 
it seems unlikely they would be (since I believe COMDAT sections serve 
the same purpose).  I thought that starting the section with "On Mac OS 
X" and including that in the menu entry was a reasonably clear way to 
mark the feature as Mac OS X -specific.  I'm certainly willing to 
include something stronger, but couldn't think of a way to do it that 
didn't seem awkward --- any suggestions?


On Tuesday, November 19, 2002, at 05:17 AM, Jim Blandy wrote:

> I have the impression that GDB doesn't need to know about these
> symbols, since the static linker has removed them by the time GDB sees
> the file.  If that's so, that should be stated explicitly.
>
> There must be more information in these stabs that allows the static
> linker to pair up a BNSYM..ENSYM region with its symbol in the
> coalesced section.  Whatever the case, the way the pairing is done
> should be explained in complete detail here.

Actually, the static linker leaves them in, so that they can be 
combined across shared libraries.  Once these patches are in, I'll be 
submitting patches to GDB to direct it to ignore BNSYM and ENSYM 
symbols.

I've tried to make the pairing algorithm a bit more clear; let me know 
if you think more is needed.

I'm also still looking for approval on the binutils portion; let me 
know if there are any issues there as well.


[-- Attachment #2: coalesced-symbols.txt --]
[-- Type: text/plain, Size: 4211 bytes --]

2002-11-18  Klee Dienes  <kdienes@apple.com>

	* stab.def (N_BNSYM): Add definition.
	(N_ENSYM): Add definition.

2002-11-18  Klee Dienes  <kdienes@apple.com>

	* stabs.texinfo (Relocatable Symbol Blocks): New section, covering
	Mac OS X coalesced symbol block markers.  Added to the "Program
	Structure" section.
	
diff --minimal -u --exclude=CVS --exclude=*.gmo cygnus.cygnus/src/include/aout/stab.def cygnus.current/src/include/aout/stab.def
--- cygnus.cygnus/src/include/aout/stab.def	Tue Mar 13 21:27:43 2001
+++ cygnus.current/src/include/aout/stab.def	Wed Oct 30 16:40:01 2002
@@ -53,6 +53,9 @@
 /* Solaris2:  Read-only data symbols.  */
 __define_stab (N_ROSYM, 0x2c, "ROSYM")
 
+/* MacOS X: The beginning of a relocatable function block - including stabs */
+__define_stab (N_BNSYM, 0x2e, "BNSYM")
+
 /* Global symbol in Pascal.
    Supposedly the value is its line number; I'm skeptical.  */
 __define_stab (N_PC, 0x30, "PC")
@@ -105,6 +108,11 @@
 
 /* New in Solaris2.  Function start/body/end line numbers.  */
 __define_stab(N_FLINE, 0x4C, "FLINE")
+
+/* Added for MacOS X, this tells the end of a relocatable function + debugging
+   info */
+
+__define_stab(N_ENSYM, 0x4E, "ENSYM")
 
 /* THE FOLLOWING TWO STAB VALUES CONFLICT.  Happily, one is for Modula-2
    and one is for C++.   Still,... */
diff -u -r1.7 stabs.texinfo
--- cygnus.cygnus/src/gdb/doc/stabs.texinfo	Tue Mar 13 21:27:43 2001
+++ cygnus.current/src/gdb/doc/stabs.texinfo	Wed Oct 30 16:40:01 2002
@@ -404,6 +404,7 @@
 * Procedures::
 * Nested Procedures::
 * Block Structure::
+* Coalesced Symbol Blocks::     Mac OS X Coalesced Symbols.
 * Alternate Entry Points::      Entering procedures except at the beginning.
 @end menu
 
@@ -740,6 +741,43 @@
 name of the symbol is @samp{.bb}, then it is the beginning of the block;
 if the name of the symbol is @samp{.be}; it is the end of the block.
 
+@node Coalesced Symbol Blocks
+@section Coalesced Symbol Blocks
+
+@findex N_BNSYM
+@findex N_ENSYM
+@cindex {coalesced symbol}
+On Mac OS X, a @dfn{coalesced symbol} is a true definition of a symbol
+that may appear one or more times in the compilation units generated
+by the compiler.
+
+The static link editor allows multiple definitions of a coalesced
+symbol without any warnings or errors.  The static link editor outputs
+only one instance of each coalesced symbol, using the first instance it
+encounters in the object files being linked.  The static link editor
+always outputs an instance of a coalesced symbol if it appears in the
+object files being linked, even if it also appears in the dynamic
+libraries being referenced.  The dynamic link editor then relocates
+such that only one instance of each coalesced symbol is used
+throughout the program.
+
+Coalesced symbols are placed by the compiler tools into sections
+flagged with the type bit S_COALESCED.  The static and dynamic linker
+look at the section type to determine that a given symbol is a
+coalesced symbol and therefore to allow multiple definitions.
+
+The static link editor divides up a coalesced section on the
+boundaries of the symbols in that section, associating the bytes of
+the section after each symbol with the preceding symbol.  An object
+file is considered malformed if a coalesced section does not have a
+symbol at the first address of the section.
+
+To allow the linker to properly manage the debug information for
+coalesced symbols, the stabs entries for a given coalesced symbol must
+be preceded by @code{N_BNSYM} and terminated with @code{N_ENSYM}.
+These stabs must be at the start and end of the given coalesced
+symbol, respectively.
+
 @node Alternate Entry Points
 @section Alternate Entry Points
 
@@ -3240,6 +3278,9 @@
 @item 0x2c N_ROSYM
 Variable in @code{.rodata} section; see @ref{Statics}.
 
+@item 0x2e N_BNSYM
+Start of a coalesced symbol block; see @ref{Coalesced Symbol Blocks}.
+
 @item 0x30     N_PC
 Global symbol (for Pascal); see @ref{N_PC}.
 
@@ -3281,6 +3322,9 @@
 
 @item 0x4c N_FLINE
 Function start/body/end line numbers (Solaris2).
+
+@item 0x4e N_ENSYM
+End of a coalesced symbol block; see @ref{Coalesced Symbol Blocks}.
 
 @item 0x50     N_EHDECL
 GNU C++ exception variable; see @ref{N_EHDECL}.