Expand doco for symbol assignment in ld scripts

[Alan Modra]

	* ld.texinfo (dot outside sections): Document effects of orphan
	section placement, and ". = ." workaround.
	* Makefile.in: Regenerate.

Index: ld/ld.texinfo
===================================================================
RCS file: /cvs/src/src/ld/ld.texinfo,v
retrieving revision 1.135
diff -u -p -r1.135 ld.texinfo
--- ld/ld.texinfo	21 Jan 2005 12:04:25 -0000	1.135
+++ ld/ld.texinfo	23 Jan 2005 05:28:22 -0000
@@ -2769,7 +2769,7 @@ The first case will define @var{symbol} 
 defined, and the value will be adjusted accordingly.
 
 The special symbol name @samp{.} indicates the location counter.  You
-may only use this within a @code{SECTIONS} command.
+may only use this within a @code{SECTIONS} command.  @xref{Location Counter}.
 
 The semicolon after @var{expression} is required.
 
@@ -4381,6 +4381,74 @@ and it will have an extra 0x600 bytes wo
 the values from the @samp{.data} input sections and before the end of
 the @samp{.data} output section itself.
 
+@cindex dot outside sections
+Setting symbols to the value of the location counter outside of an
+output section statement can result in unexpected values if the linker
+needs to place orphan sections.  For example, given the following:
+
+@smallexample
+SECTIONS
+@{
+    start_of_text = . ;
+    .text: @{ *(.text) @}
+    end_of_text = . ;
+
+    start_of_data = . ;
+    .data: @{ *(.data) @}
+    end_of_data = . ;
+@}
+@end smallexample
+
+If the linker needs to place some input section, e.g. @code{.rodata},
+not mentioned in the script, it might choose to place that section
+between @code{.text} and @code{.data}.  You might think the linker
+should place @code{.rodata} on the blank line in the above script, but
+blank lines are of no particular significance to the linker.  As well,
+the linker doesn't associate the above symbol names with their
+sections.  Instead, it assumes that all assignments or other
+statements belong to the previous output section, except for the
+special case of an assignment to @code{.}.  I.e., the linker will
+place the orphan @code{.rodata} section as if the script was written
+as follows:
+
+@smallexample
+SECTIONS
+@{
+    start_of_text = . ;
+    .text: @{ *(.text) @}
+    end_of_text = . ;
+
+    start_of_data = . ;
+    .rodata: @{ *(.rodata) @}
+    .data: @{ *(.data) @}
+    end_of_data = . ;
+@}
+@end smallexample
+
+This may or may not be the script author's intention for the value of
+@code{start_of_data}.  One way to influence the orphan section
+placement is to assign the location counter to itself, as the linker
+assumes that an assignment to @code{.} is setting the start address of
+a following output section and thus should be grouped with that
+section.  So you could write:
+
+@smallexample
+SECTIONS
+@{
+    start_of_text = . ;
+    .text: @{ *(.text) @}
+    end_of_text = . ;
+
+    . = . ;
+    start_of_data = . ;
+    .data: @{ *(.data) @}
+    end_of_data = . ;
+@}
+@end smallexample
+
+Now, the orphan @code{.rodata} section will be placed between
+@code{end_of_text} and @code{start_of_data}.
+
 @need 2000
 @node Operators
 @subsection Operators
Index: ld/Makefile.in
===================================================================
RCS file: /cvs/src/src/ld/Makefile.in,v
retrieving revision 1.182
diff -u -p -r1.182 Makefile.in
--- ld/Makefile.in	20 Jan 2005 19:37:49 -0000	1.182
+++ ld/Makefile.in	23 Jan 2005 05:28:15 -0000
@@ -629,7 +629,7 @@ deffilep.c ldgram.c ldlex.c
 
 DISTFILES = $(DIST_COMMON) $(SOURCES) $(HEADERS) $(TEXINFOS) $(EXTRA_DIST)
 
-TAR = gtar
+TAR = tar
 GZIP_ENV = --best
 SOURCES = $(ld_new_SOURCES) $(EXTRA_ld_new_SOURCES)
 OBJECTS = $(ld_new_OBJECTS)
@@ -1111,7 +1111,7 @@ distclean-generic:
 	-test -z "$(DISTCLEANFILES)" || rm -f $(DISTCLEANFILES)
 
 maintainer-clean-generic:
-	-test -z "ldlexcdeffilephdeffilepcldgramhldgramc$(MAINTAINERCLEANFILES)" || rm -f ldlexc deffileph deffilepc ldgramh ldgramc $(MAINTAINERCLEANFILES)
+	-test -z "ldlex.cdeffilep.hdeffilep.cldgram.hldgram.c$(MAINTAINERCLEANFILES)" || rm -f ldlex.c deffilep.h deffilep.c ldgram.h ldgram.c $(MAINTAINERCLEANFILES)
 mostlyclean-am:  mostlyclean-hdr mostlyclean-noinstPROGRAMS \
 		mostlyclean-compile mostlyclean-libtool \
 		mostlyclean-aminfo mostlyclean-tags mostlyclean-generic \

-- 
Alan Modra
IBM OzLabs - Linux Technology Centre