This is the mail archive of the binutils@sourceware.org mailing list for the binutils project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]