[PATCH v2 RESEND] Document .Nbyte assembler directives

[PATCH v2 RESEND] Document .Nbyte assembler directives

[Tobin C. Harding]

GAS contains directives .2byte .4byte and .8byte. These directives are
used in the test suite but are undocumented.

Add documentation to GAS section 'Assembler Directives' for each of
directive.

---

docs built using
$ make html 

Changes since v1:
 - Add menu item
 - Add ifset ELF
 - Verified .8byte truncation warning

 gas/doc/as.texinfo | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
index 8c7fdfd..9030b06 100644
--- a/gas/doc/as.texinfo
+++ b/gas/doc/as.texinfo
@@ -4555,6 +4555,11 @@ Some machine configurations provide additional directives.
 @ifclear no-space-dir
 * Zero::                        @code{.zero @var{size}}
 @end ifclear
+@ifset ELF
+* 2byte::                       @code{.2byte @var{expressions}}
+* 4byte::                       @code{.4byte @var{expressions}}
+* 8byte::                       @code{.8byte @var{bignums}}
+@end ifset
 * Deprecated::                  Deprecated Directives
 @end menu
 
@@ -7333,6 +7338,45 @@ so in can take an optional second argument of the value to store in the bytes
 instead of zero.  Using @samp{.zero} in this way would be confusing however.
 @end ifclear
 
+@cindex @code{local} directive
+This directive, which is available for ELF targets, marks each symbol in
+the comma-separated list of @code{names} as a local symbol so that it
+will not be externally visible.  If the symbols do not already exist,
+they will be created.
+
+@ifset ELF
+@node 2byte
+@section @code{.2byte @var{expressions}}
+
+@cindex @code{2byte} directive
+@cindex two-byte integer
+@cindex integer, 2-byte
+This directive @code{.2byte}, which is available for ELF targets, expects zero
+or more expressions, separated by commas. Each expression is assembled into the
+next two bytes.
+
+@node 4byte
+@section @code{.4byte @var{expressions}}
+
+@cindex @code{4byte} directive
+@cindex four-byte integer
+@cindex integer, 4-byte
+This directive @code{.4byte}, which is available for ELF targets, expects zero
+or more expressions, separated by commas. Each expression is assembled into the
+next four bytes.
+
+@node 8byte
+@section @code{.8byte @var{bignums}}
+
+@cindex @code{8byte} directive
+This directive @code{.8byte}, which is available for ELF targets, expects zero
+or more bignums, separated by commas.  For each bignum, it emits
+an 8-byte integer.  If the bignum won't fit in 8 bytes, it prints a
+warning message; and just takes the lowest order 8 bytes of the bignum.
+@cindex eight-byte integer
+@cindex integer, 8-byte
+@end ifset
+
 @node Deprecated
 @section Deprecated Directives
 
-- 
2.7.4

Re: [PATCH v2 RESEND] Document .Nbyte assembler directives

[Richard Earnshaw (lists)]

On 06/03/17 05:57, Tobin C. Harding wrote:
> GAS contains directives .2byte .4byte and .8byte. These directives are
> used in the test suite but are undocumented.
> 
> Add documentation to GAS section 'Assembler Directives' for each of
> directive.
> 
> ---
> 
> docs built using
> $ make html 
> 
> Changes since v1:
>  - Add menu item
>  - Add ifset ELF
>  - Verified .8byte truncation warning
> 
>  gas/doc/as.texinfo | 44 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 44 insertions(+)
> 
> diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
> index 8c7fdfd..9030b06 100644
> --- a/gas/doc/as.texinfo
> +++ b/gas/doc/as.texinfo
> @@ -4555,6 +4555,11 @@ Some machine configurations provide additional directives.
>  @ifclear no-space-dir
>  * Zero::                        @code{.zero @var{size}}
>  @end ifclear
> +@ifset ELF
> +* 2byte::                       @code{.2byte @var{expressions}}
> +* 4byte::                       @code{.4byte @var{expressions}}
> +* 8byte::                       @code{.8byte @var{bignums}}
> +@end ifset
>  * Deprecated::                  Deprecated Directives
>  @end menu
>  
> @@ -7333,6 +7338,45 @@ so in can take an optional second argument of the value to store in the bytes
>  instead of zero.  Using @samp{.zero} in this way would be confusing however.
>  @end ifclear
>  
> +@cindex @code{local} directive
> +This directive, which is available for ELF targets, marks each symbol in
> +the comma-separated list of @code{names} as a local symbol so that it
> +will not be externally visible.  If the symbols do not already exist,
> +they will be created.

Why zero or more?  What happens if there are zero expressions?  Do I get
a single entry inserted (with what), or nothing?

I think it's also worth pointing out that these:
- Don't align (even if .short, .word, etc would)
- Might affect the choice of relocation in a target-dependent manner.
- Follow the natural endian model for the target (sort of expected, but
probably worth stating anyway).

Given the above, it might be worth reworking this so that all three
directives come in a single block with a common description; or put all
the information in the first and reference it in the subsequent entries.

R.

> +
> +@ifset ELF
> +@node 2byte
> +@section @code{.2byte @var{expressions}}
> +
> +@cindex @code{2byte} directive
> +@cindex two-byte integer
> +@cindex integer, 2-byte
> +This directive @code{.2byte}, which is available for ELF targets, expects zero
> +or more expressions, separated by commas. Each expression is assembled into the
> +next two bytes.
> +
> +@node 4byte
> +@section @code{.4byte @var{expressions}}
> +
> +@cindex @code{4byte} directive
> +@cindex four-byte integer
> +@cindex integer, 4-byte
> +This directive @code{.4byte}, which is available for ELF targets, expects zero
> +or more expressions, separated by commas. Each expression is assembled into the
> +next four bytes.
> +
> +@node 8byte
> +@section @code{.8byte @var{bignums}}
> +
> +@cindex @code{8byte} directive
> +This directive @code{.8byte}, which is available for ELF targets, expects zero
> +or more bignums, separated by commas.  For each bignum, it emits
> +an 8-byte integer.  If the bignum won't fit in 8 bytes, it prints a
> +warning message; and just takes the lowest order 8 bytes of the bignum.
> +@cindex eight-byte integer
> +@cindex integer, 8-byte
> +@end ifset
> +
>  @node Deprecated
>  @section Deprecated Directives
>  
> 

Re: [PATCH v2 RESEND] Document .Nbyte assembler directives

[Nick Clifton]

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

Hi Richard,

> Why zero or more?

No idea - maybe it was so that gcc could generate these directives without
having to check that there always was a value to be generated ?

> What happens if there are zero expressions?  Do I get
> a single entry inserted (with what), or nothing?
> 
> I think it's also worth pointing out that these:
> - Don't align (even if .short, .word, etc would)
> - Might affect the choice of relocation in a target-dependent manner.
> - Follow the natural endian model for the target (sort of expected, but
> probably worth stating anyway).
> 
> Given the above, it might be worth reworking this so that all three
> directives come in a single block with a common description; or put all
> the information in the first and reference it in the subsequent entries.

Is this what you had in mind:

Cheers
  Nick


[-- Attachment #2: as.texinfo.patch --]
[-- Type: text/x-patch, Size: 2772 bytes --]

diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
index 3b3e931..20791cc 100644
--- a/gas/doc/as.texinfo
+++ b/gas/doc/as.texinfo
@@ -7345,10 +7345,19 @@ instead of zero.  Using @samp{.zero} in this way would be confusing however.
 @cindex two-byte integer
 @cindex integer, 2-byte
 
-This directive expects zero or more expressions, separated by commas.  Each
-expression is evaluated and placed in the next two bytes of the current
-section.  If an expression will not fit in two bytes, a warning message
-is displayed and the lowest two bytes of the expression's value are used.
+This directive expects zero or more expressions, separated by commas.  If there
+are no expressions then the directive does nothing.  Otherwise each expression
+is evaluated in turn and placed in the next two bytes of the current output
+section, using the endian model of the target.  If an expression will not fit
+in two bytes, a warning message is displayed and the lowest two bytes of the
+expression's value are used.  If an expression cannot be evaluated at assembly
+time then relocations will be generated in order to compute the value at link
+time.  
+
+This directive does not apply any alignment before or after inserting the
+values.  As a result of this, if relocations are generated, they may be
+different from those used for inserting values with a guaranteed alignment.
+
 This directive is only available for ELF targets,
 
 @node 4byte
@@ -7357,11 +7366,8 @@ This directive is only available for ELF targets,
 @cindex four-byte integer
 @cindex integer, 4-byte
 
-This directive expects zero or more expressions, separated by commas.  Each
-expression is evaluated and placed in the next four bytes of the current
-section.  If an expression will not fit in four bytes, a warning message
-is displayed and the lowest four bytes of the expression's value are used.
-This directive is only available for ELF targets,
+Like the @option{.2byte} directive, except that it inserts unaligned, four byte
+long values into the output.
 
 @node 8byte
 @section @code{.8byte @var{expression} [, @var{expression}]*}
@@ -7369,11 +7375,9 @@ This directive is only available for ELF targets,
 @cindex eight-byte integer
 @cindex integer, 8-byte
 
-This directive expects zero or more expressions, separated by commas.  Each
-expression is evaluated and the resulting bignum is placed in the next eight
-bytes of the current section.  If an expression will not fit in eight bytes, a
-warning message is displayed and the lowest eight bytes of the expression's
-value are used.  This directive is only available for ELF targets,
+Like the @option{.8byte} directive, except that it inserts unaligned, eight
+byte long bignum values into the output.
+
 @end ifset
 
 @node Deprecated

Re: [PATCH v2 RESEND] Document .Nbyte assembler directives

[Richard Earnshaw (lists)]

On 20/03/17 15:16, Nick Clifton wrote:
> Hi Richard,
> 
>> Why zero or more?
> 
> No idea - maybe it was so that gcc could generate these directives without
> having to check that there always was a value to be generated ?
> 
>> What happens if there are zero expressions?  Do I get
>> a single entry inserted (with what), or nothing?
>>
>> I think it's also worth pointing out that these:
>> - Don't align (even if .short, .word, etc would)
>> - Might affect the choice of relocation in a target-dependent manner.
>> - Follow the natural endian model for the target (sort of expected, but
>> probably worth stating anyway).
>>
>> Given the above, it might be worth reworking this so that all three
>> directives come in a single block with a common description; or put all
>> the information in the first and reference it in the subsequent entries.
> 
> Is this what you had in mind:
> 
> Cheers
>   Nick
> 
> 
> as.texinfo.patch
> 
> 
> diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
> index 3b3e931..20791cc 100644
> --- a/gas/doc/as.texinfo
> +++ b/gas/doc/as.texinfo
> @@ -7345,10 +7345,19 @@ instead of zero.  Using @samp{.zero} in this way would be confusing however.
>  @cindex two-byte integer
>  @cindex integer, 2-byte
>  
> -This directive expects zero or more expressions, separated by commas.  Each
> -expression is evaluated and placed in the next two bytes of the current
> -section.  If an expression will not fit in two bytes, a warning message
> -is displayed and the lowest two bytes of the expression's value are used.
> +This directive expects zero or more expressions, separated by commas.  If there
> +are no expressions then the directive does nothing.  Otherwise each expression
> +is evaluated in turn and placed in the next two bytes of the current output
> +section, using the endian model of the target.  If an expression will not fit
> +in two bytes, a warning message is displayed and the lowest two bytes of the

I'd use 'least significant' rather than lowest, but otherwise I think
this is much better.

R.

> +expression's value are used.  If an expression cannot be evaluated at assembly
> +time then relocations will be generated in order to compute the value at link
> +time.  
> +
> +This directive does not apply any alignment before or after inserting the
> +values.  As a result of this, if relocations are generated, they may be
> +different from those used for inserting values with a guaranteed alignment.
> +
>  This directive is only available for ELF targets,
>  
>  @node 4byte
> @@ -7357,11 +7366,8 @@ This directive is only available for ELF targets,
>  @cindex four-byte integer
>  @cindex integer, 4-byte
>  
> -This directive expects zero or more expressions, separated by commas.  Each
> -expression is evaluated and placed in the next four bytes of the current
> -section.  If an expression will not fit in four bytes, a warning message
> -is displayed and the lowest four bytes of the expression's value are used.
> -This directive is only available for ELF targets,
> +Like the @option{.2byte} directive, except that it inserts unaligned, four byte
> +long values into the output.
>  
>  @node 8byte
>  @section @code{.8byte @var{expression} [, @var{expression}]*}
> @@ -7369,11 +7375,9 @@ This directive is only available for ELF targets,
>  @cindex eight-byte integer
>  @cindex integer, 8-byte
>  
> -This directive expects zero or more expressions, separated by commas.  Each
> -expression is evaluated and the resulting bignum is placed in the next eight
> -bytes of the current section.  If an expression will not fit in eight bytes, a
> -warning message is displayed and the lowest eight bytes of the expression's
> -value are used.  This directive is only available for ELF targets,
> +Like the @option{.8byte} directive, except that it inserts unaligned, eight
> +byte long bignum values into the output.
> +
>  @end ifset
>  
>  @node Deprecated
> 

Re: [PATCH v2 RESEND] Document .Nbyte assembler directives

[Sebastian Huber]

On 07/03/17 10:13, Alan Modra wrote:
[...]
> makeinfo 6.1 worked fine..
>
> So I built makeinfo 4.13, and the problem is fixed as follows:
>      
> diff --git a/gas/ChangeLog b/gas/ChangeLog
> index 4153dbe..7949343 100644
> --- a/gas/ChangeLog
> +++ b/gas/ChangeLog
> @@ -1,3 +1,7 @@
> +2017-03-07  Alan Modra  <amodra@gmail.com>
> +
> +	* doc/as.texinfo (2byte, 4byte, 8byte): Correct @section placement.

Thanks, it works fine now.

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber@embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.

Re: [PATCH v2 RESEND] Document .Nbyte assembler directives

[Alan Modra]

On Tue, Mar 07, 2017 at 09:40:48AM +0100, Sebastian Huber wrote:
> On 07/03/17 07:36, Alan Modra wrote:
> >I've committed this variant.  nios2 and pru also document these
> >directives, mentioning that they are unaligned, so I've left that
> >target specific doco in place.
> >
> >diff --git a/gas/ChangeLog b/gas/ChangeLog
> >index f9af65d6..4153dbe 100644
> >--- a/gas/ChangeLog
> >+++ b/gas/ChangeLog
> >@@ -1,3 +1,9 @@
> >+2017-03-07  Tobin C. Harding  <me@tobin.cc>
> >+	    Alan Modra  <amodra@gmail.com>
> >+
> >+	* doc/as.texinfo (2byte, 4byte, 8byte): Document.
> >+	* doc/c-arm.texi (2byte, 4byte, 8byte): Omit if ELF.
> 
> With this patch I get now using makeinfo (GNU texinfo) 4.13:
[snip]
> /home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7362: `8byte'
> has no Up field (perhaps incorrect sectioning?).

makeinfo 6.1 worked fine..

So I built makeinfo 4.13, and the problem is fixed as follows:
    
diff --git a/gas/ChangeLog b/gas/ChangeLog
index 4153dbe..7949343 100644
--- a/gas/ChangeLog
+++ b/gas/ChangeLog
@@ -1,3 +1,7 @@
+2017-03-07  Alan Modra  <amodra@gmail.com>
+
+	* doc/as.texinfo (2byte, 4byte, 8byte): Correct @section placement.
+
 2017-03-07  Tobin C. Harding  <me@tobin.cc>
 	    Alan Modra  <amodra@gmail.com>
 
diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
index 0a70d7c..a8f014b 100644
--- a/gas/doc/as.texinfo
+++ b/gas/doc/as.texinfo
@@ -7340,30 +7340,30 @@ instead of zero.  Using @samp{.zero} in this way would be confusing however.
 
 @ifset ELF
 @node 2byte
+@section @code{.2byte @var{expression} [, @var{expression}]*}
 @cindex @code{2byte} directive
 @cindex two-byte integer
 @cindex integer, 2-byte
-@section @code{.2byte @var{expression} [, @var{expression}]*}
 
 This directive @code{.2byte}, which is available for ELF targets, expects zero
 or more expressions, separated by commas. Each expression is assembled into the
 next two bytes.
 
 @node 4byte
+@section @code{.4byte @var{expression} [, @var{expression}]*}
 @cindex @code{4byte} directive
 @cindex four-byte integer
 @cindex integer, 4-byte
-@section @code{.4byte @var{expression} [, @var{expression}]*}
 
 This directive @code{.4byte}, which is available for ELF targets, expects zero
 or more expressions, separated by commas. Each expression is assembled into the
 next four bytes.
 
 @node 8byte
+@section @code{.8byte @var{expression} [, @var{expression}]*}
 @cindex @code{8byte} directive
 @cindex eight-byte integer
 @cindex integer, 8-byte
-@section @code{.8byte @var{expression} [, @var{expression}]*}
 
 This directive @code{.8byte}, which is available for ELF targets, expects zero
 or more bignums, separated by commas.  For each bignum, it emits

-- 
Alan Modra
Australia Development Lab, IBM

Re: [PATCH v2 RESEND] Document .Nbyte assembler directives

[Tobin C. Harding]

On Mon, Mar 06, 2017 at 10:04:20PM +0100, Pierre Muller wrote:
> Hi all,
> 
>   I am just curious about what I read in your documentation improvement.
> 
>   You state that, for .8byte
> there is a warning if the bignum doesn't fit into an 8 byte integer,
> but there is nothing similar for .2byte and .4byte.

Good catch, thanks. There are warnings for .2byte and .4byte
also. Attempting to patch it now.

thanks,
Tobin.

Re: [PATCH v2 RESEND] Document .Nbyte assembler directives

[Tobin C. Harding]

On Tue, Mar 07, 2017 at 09:40:48AM +0100, Sebastian Huber wrote:
> On 07/03/17 07:36, Alan Modra wrote:
> >I've committed this variant.  nios2 and pru also document these
> >directives, mentioning that they are unaligned, so I've left that
> >target specific doco in place.
> >
> >diff --git a/gas/ChangeLog b/gas/ChangeLog
> >index f9af65d6..4153dbe 100644
> >--- a/gas/ChangeLog
> >+++ b/gas/ChangeLog
> >@@ -1,3 +1,9 @@
> >+2017-03-07  Tobin C. Harding  <me@tobin.cc>
> >+	    Alan Modra  <amodra@gmail.com>
> >+
> >+	* doc/as.texinfo (2byte, 4byte, 8byte): Document.
> >+	* doc/c-arm.texi (2byte, 4byte, 8byte): Omit if ELF.
> 
> With this patch I get now using makeinfo (GNU texinfo) 4.13:
> 
> make[4]: Entering directory
> `/build/git-build/b-binutils-git-powerpc-rtems4.12/gas/doc'
> make[4]: Nothing to be done for `install-exec-am'.
> restore=: && backupdir=".am$$" && \
> rm -rf $backupdir && mkdir $backupdir && \
> if (makeinfo --split-size=5000000 --split-size=5000000 --version) >/dev/null
> 2>&1; then \
>   for f in as.info as.info-[0-9] as.info-[0-9][0-9] as.i[0-9]
> as.i[0-9][0-9]; do \
>     if test -f $f; then mv $f $backupdir; restore=mv; else :; fi; \
>   done; \
> else :; fi && \
> if makeinfo --split-size=5000000 --split-size=5000000 -I
> "/home/EB/sebastian_h/archive/binutils-git/gas/doc" -I
> "/home/EB/sebastian_h/archive/binutils-git/gas/../libiberty" -I
> "/home/EB/sebastian_h/archive/binutils-git/gas/../bfd/doc" -I ../../bfd/doc
> -I /home/EB/sebastian_h/archive/binutils-git/gas/doc \
>  -o as.info `test -f 'as.texinfo' || echo
> '/home/EB/sebastian_h/archive/binutils-git/gas/doc/'`as.texinfo; \
> then \
>   rc=0; \
> else \
>   rc=$?; \
>   $restore $backupdir/* `echo "./as.info" | sed 's|[^/]*$||'`; \
> fi; \
> rm -rf $backupdir; exit $rc
> /home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7342: Node
> `2byte' requires a sectioning command (e.g., @unnumberedsubsec).
> /home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7352: Node
> `4byte' requires a sectioning command (e.g., @unnumberedsubsec).
> /home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7362: Node
> `8byte' requires a sectioning command (e.g., @unnumberedsubsec).
> /home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7374: Prev
> field of node `Deprecated' not pointed to.
> /home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7362: This node
> (8byte) has the bad Next.
> /home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7362: `8byte'
> has no Up field (perhaps incorrect sectioning?).
> /home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7352: `4byte'
> has no Up field (perhaps incorrect sectioning?).
> /home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7342: `2byte'
> has no Up field (perhaps incorrect sectioning?).
> /home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7330: Next
> field of node `Zero' not pointed to (perhaps incorrect sectioning?).
> /home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7342: This node
> (2byte) has the bad Prev.
> makeinfo: Removing output file `as.info' due to errors; use --force to
> preserve.

Builds with the following version;

$ makeinfo --version
texi2any (GNU texinfo) 6.1

Does the patch need modifying to build on 4.13?

thanks,
Tobin.

Re: [PATCH v2 RESEND] Document .Nbyte assembler directives

[Sebastian Huber]

On 07/03/17 07:36, Alan Modra wrote:
> I've committed this variant.  nios2 and pru also document these
> directives, mentioning that they are unaligned, so I've left that
> target specific doco in place.
>
> diff --git a/gas/ChangeLog b/gas/ChangeLog
> index f9af65d6..4153dbe 100644
> --- a/gas/ChangeLog
> +++ b/gas/ChangeLog
> @@ -1,3 +1,9 @@
> +2017-03-07  Tobin C. Harding  <me@tobin.cc>
> +	    Alan Modra  <amodra@gmail.com>
> +
> +	* doc/as.texinfo (2byte, 4byte, 8byte): Document.
> +	* doc/c-arm.texi (2byte, 4byte, 8byte): Omit if ELF.

With this patch I get now using makeinfo (GNU texinfo) 4.13:

make[4]: Entering directory 
`/build/git-build/b-binutils-git-powerpc-rtems4.12/gas/doc'
make[4]: Nothing to be done for `install-exec-am'.
restore=: && backupdir=".am$$" && \
rm -rf $backupdir && mkdir $backupdir && \
if (makeinfo --split-size=5000000 --split-size=5000000 --version) 
 >/dev/null 2>&1; then \
   for f in as.info as.info-[0-9] as.info-[0-9][0-9] as.i[0-9] 
as.i[0-9][0-9]; do \
     if test -f $f; then mv $f $backupdir; restore=mv; else :; fi; \
   done; \
else :; fi && \
if makeinfo --split-size=5000000 --split-size=5000000 -I 
"/home/EB/sebastian_h/archive/binutils-git/gas/doc" -I 
"/home/EB/sebastian_h/archive/binutils-git/gas/../libiberty" -I 
"/home/EB/sebastian_h/archive/binutils-git/gas/../bfd/doc" -I 
../../bfd/doc  -I /home/EB/sebastian_h/archive/binutils-git/gas/doc \
  -o as.info `test -f 'as.texinfo' || echo 
'/home/EB/sebastian_h/archive/binutils-git/gas/doc/'`as.texinfo; \
then \
   rc=0; \
else \
   rc=$?; \
   $restore $backupdir/* `echo "./as.info" | sed 's|[^/]*$||'`; \
fi; \
rm -rf $backupdir; exit $rc
/home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7342: Node 
`2byte' requires a sectioning command (e.g., @unnumberedsubsec).
/home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7352: Node 
`4byte' requires a sectioning command (e.g., @unnumberedsubsec).
/home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7362: Node 
`8byte' requires a sectioning command (e.g., @unnumberedsubsec).
/home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7374: Prev 
field of node `Deprecated' not pointed to.
/home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7362: This 
node (8byte) has the bad Next.
/home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7362: 
`8byte' has no Up field (perhaps incorrect sectioning?).
/home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7352: 
`4byte' has no Up field (perhaps incorrect sectioning?).
/home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7342: 
`2byte' has no Up field (perhaps incorrect sectioning?).
/home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7330: Next 
field of node `Zero' not pointed to (perhaps incorrect sectioning?).
/home/EB/sebastian_h/archive/binutils-git/gas/doc/as.texinfo:7342: This 
node (2byte) has the bad Prev.
makeinfo: Removing output file `as.info' due to errors; use --force to 
preserve.

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber@embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.

Re: [PATCH v2 RESEND] Document .Nbyte assembler directives

[Alan Modra]

I've committed this variant.  nios2 and pru also document these
directives, mentioning that they are unaligned, so I've left that
target specific doco in place.

diff --git a/gas/ChangeLog b/gas/ChangeLog
index f9af65d6..4153dbe 100644
--- a/gas/ChangeLog
+++ b/gas/ChangeLog
@@ -1,3 +1,9 @@
+2017-03-07  Tobin C. Harding  <me@tobin.cc>
+	    Alan Modra  <amodra@gmail.com>
+
+	* doc/as.texinfo (2byte, 4byte, 8byte): Document.
+	* doc/c-arm.texi (2byte, 4byte, 8byte): Omit if ELF.
+
 2017-03-06  H.J. Lu  <hongjiu.lu@intel.com>
 
 	* config/tc-i386.c (cpu_arch): Add .cet.
diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
index 8c7fdfd..0a70d7c 100644
--- a/gas/doc/as.texinfo
+++ b/gas/doc/as.texinfo
@@ -4555,6 +4555,11 @@ Some machine configurations provide additional directives.
 @ifclear no-space-dir
 * Zero::                        @code{.zero @var{size}}
 @end ifclear
+@ifset ELF
+* 2byte::                       @code{.2byte @var{expressions}}
+* 4byte::                       @code{.4byte @var{expressions}}
+* 8byte::                       @code{.8byte @var{bignums}}
+@end ifset
 * Deprecated::                  Deprecated Directives
 @end menu
 
@@ -7333,6 +7338,39 @@ so in can take an optional second argument of the value to store in the bytes
 instead of zero.  Using @samp{.zero} in this way would be confusing however.
 @end ifclear
 
+@ifset ELF
+@node 2byte
+@cindex @code{2byte} directive
+@cindex two-byte integer
+@cindex integer, 2-byte
+@section @code{.2byte @var{expression} [, @var{expression}]*}
+
+This directive @code{.2byte}, which is available for ELF targets, expects zero
+or more expressions, separated by commas. Each expression is assembled into the
+next two bytes.
+
+@node 4byte
+@cindex @code{4byte} directive
+@cindex four-byte integer
+@cindex integer, 4-byte
+@section @code{.4byte @var{expression} [, @var{expression}]*}
+
+This directive @code{.4byte}, which is available for ELF targets, expects zero
+or more expressions, separated by commas. Each expression is assembled into the
+next four bytes.
+
+@node 8byte
+@cindex @code{8byte} directive
+@cindex eight-byte integer
+@cindex integer, 8-byte
+@section @code{.8byte @var{expression} [, @var{expression}]*}
+
+This directive @code{.8byte}, which is available for ELF targets, expects zero
+or more bignums, separated by commas.  For each bignum, it emits
+an 8-byte integer.  If the bignum won't fit in 8 bytes, it prints a
+warning message; and just takes the lowest order 8 bytes of the bignum.
+@end ifset
+
 @node Deprecated
 @section Deprecated Directives
 
diff --git a/gas/doc/c-arm.texi b/gas/doc/c-arm.texi
index 391c396..29630a5 100644
--- a/gas/doc/c-arm.texi
+++ b/gas/doc/c-arm.texi
@@ -594,6 +594,7 @@ The ARM family uses @sc{ieee} floating-point numbers.
 
 @c AAAAAAAAAAAAAAAAAAAAAAAAA
 
+@ifclear ELF
 @cindex @code{.2byte} directive, ARM
 @cindex @code{.4byte} directive, ARM
 @cindex @code{.8byte} directive, ARM
@@ -601,6 +602,7 @@ The ARM family uses @sc{ieee} floating-point numbers.
 @itemx .4byte @var{expression} [, @var{expression}]*
 @itemx .8byte @var{expression} [, @var{expression}]*
 These directives write 2, 4 or 8 byte values to the output section.
+@end ifclear
 
 @cindex @code{.align} directive, ARM
 @item .align @var{expression} [, @var{expression}]

-- 
Alan Modra
Australia Development Lab, IBM

Re: [PATCH v2 RESEND] Document .Nbyte assembler directives

[Alan Modra]

On Mon, Mar 06, 2017 at 10:04:20PM +0100, Pierre Muller wrote:
> is there any alignment done?

There is no simple answer.  It depends on the target and the section.
Some targets align, but not for .eh_frame and debug sections.

Some targets align everywhere unless ".align 0" was the last .align
directive seen.

Given that they were invented for debug info, it would have been
better if they never aligned.

-- 
Alan Modra
Australia Development Lab, IBM

Re: [PATCH v2 RESEND] Document .Nbyte assembler directives

[Tobin C. Harding]

On Mon, Mar 06, 2017 at 10:04:20PM +0100, Pierre Muller wrote:
> Hi all,
> 
>   I am just curious about what I read in your documentation improvement.
> 
>   You state that, for .8byte
> there is a warning if the bignum doesn't fit into an 8 byte integer,
> but there is nothing similar for .2byte and .4byte.

thanks for the query. I will hack up some test code and see if I can
come back to you with an answer.

> 
>   Should I understand that there is no check and no warning for the two
> later?
> Another question I had was about alignment:
> is there any alignment done?
> 
> Our could a .8byte end up unaligned?

I'm not sure I will be able to answer this one though.

> 
> 
> Just curious,

thanks,
Tobin.

RE: [PATCH v2 RESEND] Document .Nbyte assembler directives

[Pierre Muller]

Hi all,

  I am just curious about what I read in your documentation improvement.

  You state that, for .8byte
there is a warning if the bignum doesn't fit into an 8 byte integer,
but there is nothing similar for .2byte and .4byte.

  Should I understand that there is no check and no warning for the two
later?
Another question I had was about alignment:
is there any alignment done?

Our could a .8byte end up unaligned?


Just curious,

Pierre Muller
Member of the core developer team of Free Pascal
and Pascal language support maintainer for GDB.

> -----Message d'origine-----
> De : binutils-owner@sourceware.org [mailto:binutils-
> owner@sourceware.org] De la part de Tobin C. Harding
> Envoyé : lundi 6 mars 2017 06:58
> À : Alan Modra
> Cc : binutils@sourceware.org; Tobin C . Harding
> Objet : [PATCH v2 RESEND] Document .Nbyte assembler directives
> 
> GAS contains directives .2byte .4byte and .8byte. These directives are
> used in the test suite but are undocumented.
> 
> Add documentation to GAS section 'Assembler Directives' for each of
> directive.
> 
> ---
> 
> docs built using
> $ make html
> 
> Changes since v1:
>  - Add menu item
>  - Add ifset ELF
>  - Verified .8byte truncation warning
> 
>  gas/doc/as.texinfo | 44 ++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 44 insertions(+)
> 
> diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
> index 8c7fdfd..9030b06 100644
> --- a/gas/doc/as.texinfo
> +++ b/gas/doc/as.texinfo
> @@ -4555,6 +4555,11 @@ Some machine configurations provide additional
> directives.
>  @ifclear no-space-dir
>  * Zero::                        @code{.zero @var{size}}
>  @end ifclear
> +@ifset ELF
> +* 2byte::                       @code{.2byte @var{expressions}}
> +* 4byte::                       @code{.4byte @var{expressions}}
> +* 8byte::                       @code{.8byte @var{bignums}}
> +@end ifset
>  * Deprecated::                  Deprecated Directives
>  @end menu
> 
> @@ -7333,6 +7338,45 @@ so in can take an optional second argument of
> the value to store in the bytes
>  instead of zero.  Using @samp{.zero} in this way would be confusing
> however.
>  @end ifclear
> 
> +@cindex @code{local} directive
> +This directive, which is available for ELF targets, marks each symbol
> in
> +the comma-separated list of @code{names} as a local symbol so that it
> +will not be externally visible.  If the symbols do not already exist,
> +they will be created.
> +
> +@ifset ELF
> +@node 2byte
> +@section @code{.2byte @var{expressions}}
> +
> +@cindex @code{2byte} directive
> +@cindex two-byte integer
> +@cindex integer, 2-byte
> +This directive @code{.2byte}, which is available for ELF targets,
> expects zero
> +or more expressions, separated by commas. Each expression is assembled
> into the
> +next two bytes.
> +
> +@node 4byte
> +@section @code{.4byte @var{expressions}}
> +
> +@cindex @code{4byte} directive
> +@cindex four-byte integer
> +@cindex integer, 4-byte
> +This directive @code{.4byte}, which is available for ELF targets,
> expects zero
> +or more expressions, separated by commas. Each expression is assembled
> into the
> +next four bytes.
> +
> +@node 8byte
> +@section @code{.8byte @var{bignums}}
> +
> +@cindex @code{8byte} directive
> +This directive @code{.8byte}, which is available for ELF targets,
> expects zero
> +or more bignums, separated by commas.  For each bignum, it emits
> +an 8-byte integer.  If the bignum won't fit in 8 bytes, it prints a
> +warning message; and just takes the lowest order 8 bytes of the
> bignum.
> +@cindex eight-byte integer
> +@cindex integer, 8-byte
> +@end ifset
> +
>  @node Deprecated
>  @section Deprecated Directives
> 
> --
> 2.7.4

[PATCH v2 RESEND] Document .Nbyte assembler directives

[Tobin C. Harding]

GAS contains directives .2byte .4byte and .8byte. These directives are
used in the test suite but are undocumented.

Add documentation to GAS section 'Assembler Directives' for each of
directive.

---

docs built using
$ make html 

Changes since v1:
 - Add menu item
 - Add ifset ELF
 - Verified .8byte truncation warning

 gas/doc/as.texinfo | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/gas/doc/as.texinfo b/gas/doc/as.texinfo
index 8c7fdfd..9030b06 100644
--- a/gas/doc/as.texinfo
+++ b/gas/doc/as.texinfo
@@ -4555,6 +4555,11 @@ Some machine configurations provide additional directives.
 @ifclear no-space-dir
 * Zero::                        @code{.zero @var{size}}
 @end ifclear
+@ifset ELF
+* 2byte::                       @code{.2byte @var{expressions}}
+* 4byte::                       @code{.4byte @var{expressions}}
+* 8byte::                       @code{.8byte @var{bignums}}
+@end ifset
 * Deprecated::                  Deprecated Directives
 @end menu
 
@@ -7333,6 +7338,45 @@ so in can take an optional second argument of the value to store in the bytes
 instead of zero.  Using @samp{.zero} in this way would be confusing however.
 @end ifclear
 
+@cindex @code{local} directive
+This directive, which is available for ELF targets, marks each symbol in
+the comma-separated list of @code{names} as a local symbol so that it
+will not be externally visible.  If the symbols do not already exist,
+they will be created.
+
+@ifset ELF
+@node 2byte
+@section @code{.2byte @var{expressions}}
+
+@cindex @code{2byte} directive
+@cindex two-byte integer
+@cindex integer, 2-byte
+This directive @code{.2byte}, which is available for ELF targets, expects zero
+or more expressions, separated by commas. Each expression is assembled into the
+next two bytes.
+
+@node 4byte
+@section @code{.4byte @var{expressions}}
+
+@cindex @code{4byte} directive
+@cindex four-byte integer
+@cindex integer, 4-byte
+This directive @code{.4byte}, which is available for ELF targets, expects zero
+or more expressions, separated by commas. Each expression is assembled into the
+next four bytes.
+
+@node 8byte
+@section @code{.8byte @var{bignums}}
+
+@cindex @code{8byte} directive
+This directive @code{.8byte}, which is available for ELF targets, expects zero
+or more bignums, separated by commas.  For each bignum, it emits
+an 8-byte integer.  If the bignum won't fit in 8 bytes, it prints a
+warning message; and just takes the lowest order 8 bytes of the bignum.
+@cindex eight-byte integer
+@cindex integer, 8-byte
+@end ifset
+
 @node Deprecated
 @section Deprecated Directives
 
-- 
2.7.4