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

["Richard Earnshaw (lists)" <Richard dot Earnshaw at arm dot com>]

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
>