[RFA] Add stabs entries for coalesced symbols.

[RFA] Add stabs entries for coalesced symbols.

[Klee Dienes]

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

Ignore my previous post; I sent to the wrong lists and left off the  
ChangeLog entries:

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

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.

[Ian Lance Taylor]

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.

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.

Ian

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

[Klee Dienes]

[-- 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}.

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

[Eli Zaretskii]

On Sun, 24 Nov 2002, Klee Dienes wrote:

> [ 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. ]

The doco part is approved, but please correct this line:

  +@cindex {coalesced symbol}

Please remove the {} around the index entry text.

> 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?

You could add a @footnote saying that currently this feature is supported 
only on the Mac.

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

[Ian Lance Taylor]

Klee Dienes <klee@apple.com> writes:

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

I only intended to say that it would be nice if your documentation
mentioned COMDAT sections and SEC_LINK_DUPLICATES_DISCARD in
connection with coalesced symbols.  They are very similar (I do
understand the distinction you mention), and I believe it will help
people understand the documentation.

Ian

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

[Jim Blandy]

I like these docs a lot better, thanks.

Klee Dienes <klee@apple.com> writes:
> (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)

Does that engineer have an assignment on file?  Or does Apple have a
blanket assignment in place?

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

That is:

    the value of the N_BNYSM stab should be the start address of the
    coalesced portion (the same value as the symbol that begins the
    portion), and the value of the N_ENSYM stab should be the end address
    of the coalesced prtion (the same value as the next coalesced symbol,
    or the end of the whole coalesced section).

If that's right, then please include that language, or something
equally explicit; I'm happy to see this committed.

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

[Nick Clifton]

Hi Klee,

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

Approved - please apply (with the changes in the documentaiton already
mentioed by yourself and others).

Cheers
        Nick

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

[Klee Dienes]

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

Thanks to everyone for the feedback.  Hopefully this will be the final 
version, though I'm certainly up for more suggestions:


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

--- cygnus.cygnus/src/gdb/doc/stabs.texinfo	Sun Nov 24 05:21:06 2002
+++ cygnus.current/src/gdb/doc/stabs.texinfo	Sun Dec  8 19:26:14 2002
@@ -404,6 +404,7 @@
 * Procedures::
 * Nested Procedures::
 * Block Structure::
+* Coalesced Symbol Blocks::	Coalesced Symbol Blocks.
 * Alternate Entry Points::      Entering procedures except at the beginning.
 @end menu
 
@@ -740,6 +741,50 @@
 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 semantics of coalesced symbols are similar to
+those of sections with @code{SEC_LINK_DUPLICATES_DISCARD}
+(@code{COMDAT}) set, with the difference that coalesced symbols are
+processed on a per-symbol basis, rather than on a per-section basis.
+Currently, coalesced symbols are implemented only on Mac OS X.
+
+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 @code{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}.  The
+value of the @code{N_BNYSM} stab should be the start address of the coalesced
+portion (the same value as the symbol that begins the portion), and
+the value of the @code{N_ENSYM} stab should be the end address of the
+coalesced portion (the same value as the next coalesced symbol, or the
+end of the whole coalesced section).
+
 @node Alternate Entry Points
 @section Alternate Entry Points
 
@@ -3240,6 +3285,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 +3329,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}.

[-- Attachment #3: Type: text/plain, Size: 145 bytes --]



One question for Eli:  are you sure you want a @cindex entry for 
"coalesced symbols"?  I ask only because it's the only one in the 
document.

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

[Eli Zaretskii]

On Sun, 8 Dec 2002, Klee Dienes wrote:

> Thanks to everyone for the feedback.

Thanks for working on this.

The doco patch is approved.

> One question for Eli:  are you sure you want a @cindex entry for
> "coalesced symbols"?

Yes, I'm quite sure adding such an index entry is a Good Thing.

> I ask only because it's the only one in the
> document.

I'm afraid I don't understand the nature of your hesitance.

An index entry is a powerful means for finding information in the manual 
quickly and efficiently.  It is quick because just typing "i coalesc TAB" 
and then hitting [Enter] will take you to the section you wrote in both 
Emacs and the stand-alone Info reader.  It is efficient because index 
entries are created by humans who are supposed to consider issues that 
users are likely to think about when looking for specific information, 
and therefore the phrases included in the index are already oriented 
towards someone who searches for info.

In other words, indexing helps you use the manual as a reference.  Thus, 
whether the term "coalesced symbol" appears once or more than once in a 
manual is not important for having an index entry for it.  On the 
contrary, since there is a definitive place where the manual explains 
what a coalesced symbol is and how GDB handles it, having an index entry 
for that one place is very important.

Does that resolve your concerns?

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

[Klee Dienes]

Yes; thanks for the explanation.

Just to be clear on why I was asking, my concern wasn't that it was the 
only instance of "coalesced symbols" in the document, it was that it 
was the only instance of @cindex in the document, and I was worried 
that an index with only one entry could look awkward.  But I suspect 
after reading your response that your response would be "well, that 
just means we probably need more @cindex entries to be added".

On Monday, December 9, 2002, at 01:06 AM, Eli Zaretskii wrote:
>
>> I ask only because it's the only one in the
>> document.
>
> I'm afraid I don't understand the nature of your hesitance.
>
> An index entry is a powerful means for finding information in the 
> manual
> quickly and efficiently.  It is quick because just typing "i coalesc 
> TAB"
> and then hitting [Enter] will take you to the section you wrote in both
> Emacs and the stand-alone Info reader.  It is efficient because index
> entries are created by humans who are supposed to consider issues that
> users are likely to think about when looking for specific information,
> and therefore the phrases included in the index are already oriented
> towards someone who searches for info.
>
> In other words, indexing helps you use the manual as a reference.  
> Thus,
> whether the term "coalesced symbol" appears once or more than once in a
> manual is not important for having an index entry for it.  On the
> contrary, since there is a definitive place where the manual explains
> what a coalesced symbol is and how GDB handles it, having an index 
> entry
> for that one place is very important.
>
> Does that resolve your concerns?

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

[Eli Zaretskii]

> Date: Mon, 9 Dec 2002 01:39:38 -0500
> From: Klee Dienes <klee@apple.com>
> 
> Just to be clear on why I was asking, my concern wasn't that it was the 
> only instance of "coalesced symbols" in the document, it was that it 
> was the only instance of @cindex in the document

Hmm... that's true: stabs.texinfo doesn't use @cindex.  But OTOH it
doesn't have the command to generate the concept index, so adding
@cindex won't hurt.

> But I suspect 
> after reading your response that your response would be "well, that 
> just means we probably need more @cindex entries to be added".

Yes, that's true.

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

[Jim Ingham]

Apple has a blanket assignment.

>
> Does that engineer have an assignment on file?  Or does Apple have a
> blanket assignment in place?
>
>

Jim
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-
Jim Ingham                                                           
jingham@apple.com
Developer Tools - gdb

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

[Eli Zaretskii]

Forwarded here, since the original message was sent to the wrong list, 
and so was my response.

---------- Forwarded message ----------
Date: Tue, 19 Nov 2002 08:11:29 +0200 (IST)
From: Eli Zaretskii <eliz@is.elta.co.il>
To: Klee Dienes <klee@apple.com>
Cc: binutils@sources.redhat.com, gdb@sources.redhat.com
Subject: Re: [RFA] Add stabs entries for coalesced symbols.


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!