[RFA] Add stabs entries for coalesced symbols.

[RFA] Add stabs entries for coalesced symbols.

[Klee Dienes]

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

The following patch adds definitions for Mac OS X -style coalesced  
symbols to aout/stab.def and stabs.texinfo.  For general documentation  
on coalesced symbols, search for N_BNSYM in the following link:

http://web.mit.edu/darwin/src/modules/cctools/RelNotes/ 
Private_CompilerTools.html

I suspect there may be a better place to "Relocatable Symbol Blocks"  
section of the TeXinfo file, but I wasn't able to find it; I'm happy to  
move it elsewhere in the document if someone can tell me a better place.


[-- Attachment #2: stabs.txt --]
[-- Type: text/plain, Size: 3347 bytes --]

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,... */

Index: stabs.texinfo
===================================================================
RCS file: /Volumes/Storage/Users/kdienes/source/cvs/cygnus/src/gdb/doc/stabs.texinfo,v
retrieving revision 1.3
diff -u -r1.3 stabs.texinfo
--- stabs.texinfo	2002/08/13 20:16:07	1.3
+++ stabs.texinfo	2002/11/18 22:37:47
@@ -404,6 +404,7 @@
 * Procedures::
 * Nested Procedures::
 * Block Structure::
+* Relocatable Symbol Blocks::   Mac OS X Coalesced Symbols.
 * Alternate Entry Points::      Entering procedures except at the beginning.
 @end menu
 
@@ -740,6 +741,29 @@
 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 Relocatable Symbol Blocks
+@section Relocatable Symbol Blocks
+
+@findex N_BNSYM
+@findex N_ENSYM
+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.
+
+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}.
+
 @node Alternate Entry Points
 @section Alternate Entry Points
 
@@ -3240,6 +3264,9 @@
 @item 0x2c N_ROSYM
 Variable in @code{.rodata} section; see @ref{Statics}.
 
+@item 0x2e N_BNSYM
+Start of a relocatble symbolblock; see @ref{Relocatable Symbol Blocks}.
+
 @item 0x30     N_PC
 Global symbol (for Pascal); see @ref{N_PC}.
 
@@ -3281,6 +3308,9 @@
 
 @item 0x4c N_FLINE
 Function start/body/end line numbers (Solaris2).
+
+@item 0x4e N_ENSYM
+End of a relocatble symbol block; see @ref{Relocatable Symbol Blocks}.
 
 @item 0x50     N_EHDECL
 GNU C++ exception variable; see @ref{N_EHDECL}.

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

[Eli Zaretskii]

On Mon, 18 Nov 2002, Klee Dienes wrote:

> I suspect there may be a better place to "Relocatable Symbol Blocks"  
> section of the TeXinfo file, but I wasn't able to find it

I don't see anything wrong with your choice, but then I'm not a stabs 
expert.  If someone thinks that another place is better, please speak up.

Your patch is approved, with the following comments/requests:


  +@node Relocatable Symbol Blocks
  +@section Relocatable Symbol Blocks

Please add a @cindex entry here for "relocatable symbol blocks".

  +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.

It is generally a good idea to have a @cindex entry for each term you put 
inside a @dfn.  The logic is that if the term is important enough to have 
it stand out in the manual, someone will want to find its description 
quickly; using index-search facilities of Info readers is just the way to 
do that.

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.

  +The static link editor allows multiple definitions of a coalesced
  +symbol without any warnings or errors. The static link editor outputs
                                        ^^^
Please make sure there are exactly 2 spaces after each period that ends a 
sentence.  This is important for TeX to typeset the printed version in a 
pleasant way.

  +@item 0x2e N_BNSYM
  +Start of a relocatble symbolblock; see @ref{Relocatable Symbol Blocks}.
                         ^^^^^^^^^^^
This should be "symbol block", I think.

Thanks!

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

[Jim Blandy]

Klee Dienes <klee@apple.com> writes:

> The following patch adds definitions for Mac OS X -style coalesced
> symbols to aout/stab.def and stabs.texinfo.  For general documentation
> on coalesced symbols, search for N_BNSYM in the following link:
> 
> http://web.mit.edu/darwin/src/modules/cctools/RelNotes/
> Private_CompilerTools.html
> 
> I suspect there may be a better place to "Relocatable Symbol Blocks"
> section of the TeXinfo file, but I wasn't able to find it; I'm happy
> to  move it elsewhere in the document if someone can tell me a better
> place.

Couldn't you call the section "Coalesced Symbol Blocks"?  That way,
someone familiar with the OS X feature would recognize that the
section was relevant to the concept.

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.