[binutils-gdb] Update the description of the linker script's TYPE directive.

[binutils-gdb] Update the description of the linker script's TYPE directive.

[Nick Clifton]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=dcb53d93eb0e773c5e63c1fdbc10ec19940e6e02

commit dcb53d93eb0e773c5e63c1fdbc10ec19940e6e02
Author: Nick Clifton <nickc@redhat.com>
Date:   Thu Dec 8 13:06:31 2022 +0000

    Update the description of the linker script's TYPE directive.
    
            PR 29861
            * ld.texi (Output Section Type): Note that setting the output
            section type only works if the section contains untyped data.

Diff:
---
 ld/ChangeLog |  6 ++++++
 ld/ld.texi   | 24 ++++++++++++++++++++++++
 2 files changed, 30 insertions(+)

diff --git a/ld/ChangeLog b/ld/ChangeLog
index e8dc0908cfa..8cff90b559b 100644
--- a/ld/ChangeLog
+++ b/ld/ChangeLog
@@ -1,3 +1,9 @@
+2022-12-08  Nick Clifton  <nickc@redhat.com>
+
+	PR 29861
+	* ld.texi (Output Section Type): Note that setting the output
+	section type only works if the section contains untyped data.
+
 2022-12-05  Nick Clifton  <nickc@redhat.com>
 
 	PR 29849
diff --git a/ld/ld.texi b/ld/ld.texi
index 3836465730c..9b937f0c072 100644
--- a/ld/ld.texi
+++ b/ld/ld.texi
@@ -5548,11 +5548,14 @@ Each output section may have a type.  The type is a keyword in
 parentheses.  The following types are defined:
 
 @table @code
+
 @item NOLOAD
 The section should be marked as not loadable, so that it will not be
 loaded into memory when the program is run.
+
 @item READONLY
 The section should be marked as read-only.
+
 @item DSECT
 @item COPY
 @item INFO
@@ -5561,6 +5564,7 @@ These type names are supported for backward compatibility, and are
 rarely used.  They all have the same effect: the section should be
 marked as not allocatable, so that no memory is allocated for the
 section when the program is run.
+
 @item TYPE = @var{type}
 Set the section type to the integer @var{type}. When generating an ELF
 output file, type names @code{SHT_PROGBITS}, @code{SHT_STRTAB},
@@ -5568,9 +5572,29 @@ output file, type names @code{SHT_PROGBITS}, @code{SHT_STRTAB},
 @code{SHT_FINI_ARRAY}, and @code{SHT_PREINIT_ARRAY} are also allowed
 for @var{type}.  It is the user's responsibility to ensure that any
 special requirements of the section type are met.
+
+Note - the TYPE only is used if some or all of the contents of the
+section do not have an implicit type of their own.  So for example:
+@smallexample
+  .foo . TYPE = SHT_PROGBITS @{ *(.bar) @}
+@end smallexample
+will set the type of section @samp{.foo} to the type of the section
+@samp{.bar} in the input files, which may not be the SHT_PROGBITS
+type.  Whereas:
+@smallexample
+  .foo . TYPE = SHT_PROGBITS @{ BYTE(1) @}
+@end smallexample
+will set the type of @samp{.foo} to SHT_PROGBBITS.  If it is necessary
+to override the type of incoming sections and force the output section
+type then an extra piece of untyped data will be needed:
+@smallexample
+  .foo . TYPE = SHT_PROGBITS @{ BYTE(1); *(.bar) @}
+@end smallexample
+
 @item READONLY ( TYPE = @var{type} )
 This form of the syntax combines the @var{READONLY} type with the
 type specified by @var{type}.
+
 @end table
 
 @kindex NOLOAD