This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC 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][doc] Document clrsb optab and fix some inconsistencies


On Wed, Jul 16, 2014 at 09:05:22AM +0100, Kyrill Tkachov wrote:
> Hi all,
> 
> I noticed we don't document the clrsb<mode>2 optab but it does exist. 
> The proposed description is based on the clrsb RTL code documentation in 
> rtl.texi.
> While we're at it, clean up the wording for some other cases in the file 
> which refer to an argument 'x' when they mean to refer to operand 1. 
> They were probably copied over from rtl.texi which does use 'x'.
> 
> Ok for trunk?
> 
> 2014-07-16  Kyrylo Tkachov  <kyrylo.tkachov@arm.com>
> 
>      * doc/md.texi (clrsb): Document.
>      (clz): Change reference to x into operand 1.
>      (ctz): Likewise.
>      (popcount): Likewise.
>      (parity): Likewise.

> commit 8f0f09fbf6e8ee8136d4977f9819ee1997f82963
> Author: Kyrylo Tkachov <kyrylo.tkachov@arm.com>
> Date:   Tue Jul 15 17:41:29 2014 +0100
> 
>     [DOC] Document clrsb optab
> 
> diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
> index fde67d7..268f625 100644
> --- a/gcc/doc/md.texi
> +++ b/gcc/doc/md.texi
> @@ -5316,10 +5316,17 @@ generating the instruction.
>  The @code{ffs} built-in function of C always uses the mode which
>  corresponds to the C data type @code{int}.
>  
> +@cindex @code{clrsb@var{m}2} instruction pattern
> +@item @samp{clrsb@var{m}2}
> +Store into operand 0 the number of redundant sign bits in operand 1, starting
> +at the most significant bit position.
> +This is one less than the number of leading sign bits (either 0 or 1),
> +with no special cases.
> +

This reads unclear to me. If I have no knowledge of clrsb the sentence:

  "This is one less than the number of leading sign bits (either 0 or 1)"

can be read as suggesting that there are either 0 or 1 leading sign bits,
with clrsb setting operand 0 to be one less than that (either -1 or 0).

I think giving the example of what "sign bits" are is unnecessary, likewise
the "with no special cases" clause. The only term which might need introducing
is what a redundant sign bit is. I also find it polite to expand the acronym
shortly after first use. I think this hunk would read clearer as:

  "Count leading redundant sign bits.

   Store into operand 0 the number of redundant sign bits in operand 1,
   starting at the most significant bit position.

   A redundant sign bit is defined as any sign bit after the first. As such,
   this count will be one less than the count of leading sign bits."

But, I defer to Gerald and your opinions, as this would be a departure of
style from the CLZ/CTZ optabs.

Thanks,
James

>  @cindex @code{clz@var{m}2} instruction pattern
>  @item @samp{clz@var{m}2}
> -Store into operand 0 the number of leading 0-bits in @var{x}, starting
> -at the most significant bit position.  If @var{x} is 0, the
> +Store into operand 0 the number of leading 0-bits in operand 1, starting
> +at the most significant bit position.  If operand 1 is 0, the
>  @code{CLZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
>  the result is undefined or has a useful value.
>  @var{m} is the mode of operand 0; operand 1's mode is
> @@ -5328,8 +5335,8 @@ operand to that mode before generating the instruction.
>  
>  @cindex @code{ctz@var{m}2} instruction pattern
>  @item @samp{ctz@var{m}2}
> -Store into operand 0 the number of trailing 0-bits in @var{x}, starting
> -at the least significant bit position.  If @var{x} is 0, the
> +Store into operand 0 the number of trailing 0-bits in operand 1, starting
> +at the least significant bit position.  If operand 1 is 0, the
>  @code{CTZ_DEFINED_VALUE_AT_ZERO} (@pxref{Misc}) macro defines if
>  the result is undefined or has a useful value.
>  @var{m} is the mode of operand 0; operand 1's mode is
> @@ -5338,15 +5345,15 @@ operand to that mode before generating the instruction.
>  
>  @cindex @code{popcount@var{m}2} instruction pattern
>  @item @samp{popcount@var{m}2}
> -Store into operand 0 the number of 1-bits in @var{x}.  @var{m} is the
> +Store into operand 0 the number of 1-bits in operand 1.  @var{m} is the
>  mode of operand 0; operand 1's mode is specified by the instruction
>  pattern, and the compiler will convert the operand to that mode before
>  generating the instruction.
>  
>  @cindex @code{parity@var{m}2} instruction pattern
>  @item @samp{parity@var{m}2}
> -Store into operand 0 the parity of @var{x}, i.e.@: the number of 1-bits
> -in @var{x} modulo 2.  @var{m} is the mode of operand 0; operand 1's mode
> +Store into operand 0 the parity of operand 1, i.e.@: the number of 1-bits
> +in operand 1 modulo 2.  @var{m} is the mode of operand 0; operand 1's mode
>  is specified by the instruction pattern, and the compiler will convert
>  the operand to that mode before generating the instruction.
>  


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