diff mbox series

[1/8] docs: Document maskload else operand and behavior.

Message ID D3DDVCBVVBLW.TBT2P6NHCBOY@gmail.com
State New
Headers show
Series [1/8] docs: Document maskload else operand and behavior. | expand

Commit Message

Robin Dapp Aug. 11, 2024, 9 p.m. UTC 
This patch amends the documentation for masked loads (maskload,
vec_mask_load_lanes, and mask_gather_load as well as their len
counterparts) with an else operand.

gcc/ChangeLog:

	* doc/md.texi: Document masked load else operand.
---
 gcc/doc/md.texi | 60 +++++++++++++++++++++++++++++++------------------
 1 file changed, 38 insertions(+), 22 deletions(-)

Comments

Richard Sandiford Aug. 12, 2024, 9:38 a.m. UTC | #1 
"Robin Dapp" <rdapp.gcc@gmail.com> writes:
> This patch amends the documentation for masked loads (maskload,
> vec_mask_load_lanes, and mask_gather_load as well as their len
> counterparts) with an else operand.
>
> gcc/ChangeLog:
>
> 	* doc/md.texi: Document masked load else operand.
> ---
>  gcc/doc/md.texi | 60 +++++++++++++++++++++++++++++++------------------
>  1 file changed, 38 insertions(+), 22 deletions(-)
>
> diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
> index 5dc0d55edd6..4047d8f58fe 100644
> --- a/gcc/doc/md.texi
> +++ b/gcc/doc/md.texi
> @@ -5017,8 +5017,9 @@ This pattern is not allowed to @code{FAIL}.
>  @item @samp{vec_mask_load_lanes@var{m}@var{n}}
>  Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional
>  mask operand (operand 2) that specifies which elements of the destination
> -vectors should be loaded.  Other elements of the destination
> -vectors are set to zero.  The operation is equivalent to:
> +vectors should be loaded.  Operand 3 is an else operand similar to the one
> +in @code{maskload}.

How about:

  Other elements of the destination vectors are taken from operand 3,
  which is an else operand similar to the one in @code{maskload}.

> +The operation is equivalent to:
>  
>  @smallexample
>  int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
> @@ -5028,7 +5029,7 @@ for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
>        operand0[i][j] = operand1[j * c + i];
>    else
>      for (i = 0; i < c; i++)
> -      operand0[i][j] = 0;
> +      operand0[i][j] = operand3;

It looks from the other patches like operand 3 is actually a vector
(which is good), so I suppose this should be operand3[j] instead.

Same for the others.

>  @end smallexample
>  
>  This pattern is not allowed to @code{FAIL}.
> [...]
> @@ -5368,8 +5379,12 @@ Operands 4 and 5 have a target-dependent scalar integer mode.
>  @cindex @code{maskload@var{m}@var{n}} instruction pattern
>  @item @samp{maskload@var{m}@var{n}}
>  Perform a masked load of vector from memory operand 1 of mode @var{m}
> -into register operand 0.  Mask is provided in register operand 2 of
> -mode @var{n}.
> +into register operand 0.  The mask is provided in register operand 2 of
> +mode @var{n}.  Operand 3 (the "else value") specifies which value is loaded
> +when the mask is unset.

I think this should clarify that operand 3 has mode @var{m}.

>  The predicate of operand 3 must only accept
> +the else values that the target actually supports.  Currently two values
> +are attempted, zero and undefined.  GCC handles an else value of zero more
> +efficiently than an undefined one.

It looks like the code has support for all-ones as well.

>  
>  This pattern is not allowed to @code{FAIL}.
>  
> @@ -5435,15 +5450,16 @@ Operands 0 and 1 have mode @var{m}, which must be a vector mode.  Operand 3
>  has whichever integer mode the target prefers.  A mask is specified in
>  operand 2 which must be of type @var{n}.  The mask has lower precedence than
>  the length and is itself subject to length masking,
> -i.e. only mask indices < (operand 3 + operand 4) are used.
> +i.e. only mask indices < (operand 4 + operand 5) are used.
> +Operand 3 is an else operand similar to the one in @code{maskload}.
>  Operand 4 conceptually has mode @code{QI}.
>  
> -Operand 2 can be a variable or a constant amount.  Operand 4 specifies a
> +Operand 2 can be a variable or a constant amount.  Operand 5 specifies a

IIUC, the old text should have said "Operand 3 can be ..." and the new
text should say "Operand 4 can be ...".  Operand 2 is the mask.

>  constant bias: it is either a constant 0 or a constant -1.  The predicate on
> -operand 4 must only accept the bias values that the target actually supports.
> +operand 5 must only accept the bias values that the target actually supports.
>  GCC handles a bias of 0 more efficiently than a bias of -1.
>  
> -If (operand 2 + operand 4) exceeds the number of elements in mode
> +If (operand 2 + operand 4 + operand 5) exceeds the number of elements in mode

Similarly, I think the old text should have said "operand 3 + operand 4"
and the new one should say "operand 4 + operand 5".  There isn't a third
term to add.

Thanks,
Richard

>  @var{m}, the behavior is undefined.
>  
>  If the target prefers the length to be measured in bytes
diff mbox series

Patch

diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index 5dc0d55edd6..4047d8f58fe 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -5017,8 +5017,9 @@  This pattern is not allowed to @code{FAIL}.
 @item @samp{vec_mask_load_lanes@var{m}@var{n}}
 Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional
 mask operand (operand 2) that specifies which elements of the destination
-vectors should be loaded.  Other elements of the destination
-vectors are set to zero.  The operation is equivalent to:
+vectors should be loaded.  Operand 3 is an else operand similar to the one
+in @code{maskload}.
+The operation is equivalent to:
 
 @smallexample
 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
@@ -5028,7 +5029,7 @@  for (j = 0; j < GET_MODE_NUNITS (@var{n}); j++)
       operand0[i][j] = operand1[j * c + i];
   else
     for (i = 0; i < c; i++)
-      operand0[i][j] = 0;
+      operand0[i][j] = operand3;
 @end smallexample
 
 This pattern is not allowed to @code{FAIL}.
@@ -5036,16 +5037,20 @@  This pattern is not allowed to @code{FAIL}.
 @cindex @code{vec_mask_len_load_lanes@var{m}@var{n}} instruction pattern
 @item @samp{vec_mask_len_load_lanes@var{m}@var{n}}
 Like @samp{vec_load_lanes@var{m}@var{n}}, but takes an additional
-mask operand (operand 2), length operand (operand 3) as well as bias operand (operand 4)
-that specifies which elements of the destination vectors should be loaded.
-Other elements of the destination vectors are undefined.  The operation is equivalent to:
+mask operand (operand 2), length operand (operand 4) as well as bias operand
+(operand 5) that specifies which elements of the destination vectors should be
+loaded.  Operand 3 is an else operand similar to the one in @code{maskload}.
+Other elements of the destination vectors are undefined.  The operation
+is equivalent to:
 
 @smallexample
 int c = GET_MODE_SIZE (@var{m}) / GET_MODE_SIZE (@var{n});
-for (j = 0; j < operand3 + operand4; j++)
-  if (operand2[j])
-    for (i = 0; i < c; i++)
+for (j = 0; j < operand4 + operand5; j++)
+  for (i = 0; i < c; i++)
+    if (operand2[j])
       operand0[i][j] = operand1[j * c + i];
+    else
+      operand0[i][j] = operand3;
 @end smallexample
 
 This pattern is not allowed to @code{FAIL}.
@@ -5125,18 +5130,24 @@  address width.
 @cindex @code{mask_gather_load@var{m}@var{n}} instruction pattern
 @item @samp{mask_gather_load@var{m}@var{n}}
 Like @samp{gather_load@var{m}@var{n}}, but takes an extra mask operand as
-operand 5.  Bit @var{i} of the mask is set if element @var{i}
+operand 5 and an else operand 6 similar to the one in @code{maskload}.
+Bit @var{i} of the mask is set if element @var{i}
 of the result should be loaded from memory and clear if element @var{i}
-of the result should be set to zero.
+of the result should be set to operand 6.
 
 @cindex @code{mask_len_gather_load@var{m}@var{n}} instruction pattern
 @item @samp{mask_len_gather_load@var{m}@var{n}}
-Like @samp{gather_load@var{m}@var{n}}, but takes an extra mask operand (operand 5),
-a len operand (operand 6) as well as a bias operand (operand 7).  Similar to mask_len_load,
-the instruction loads at most (operand 6 + operand 7) elements from memory.
+Like @samp{gather_load@var{m}@var{n}}, but takes an extra mask operand
+(operand 5) and an else operand (operand 6) similar to the one in
+@code{maskload} as well as a len operand (operand 7) and a bias operand
+(operand 8).
+
+Similar to mask_len_load the instruction loads at
+most (operand 7 + operand 8) elements from memory.
 Bit @var{i} of the mask is set if element @var{i} of the result should
-be loaded from memory and clear if element @var{i} of the result should be undefined.
-Mask elements @var{i} with @var{i} > (operand 6 + operand 7) are ignored.
+be loaded from memory and clear if element @var{i} of the result should
+be set to operand 6.
+Mask elements @var{i} with @var{i} > (operand 7 + operand 8) are ignored.
 
 @cindex @code{scatter_store@var{m}@var{n}} instruction pattern
 @item @samp{scatter_store@var{m}@var{n}}
@@ -5368,8 +5379,12 @@  Operands 4 and 5 have a target-dependent scalar integer mode.
 @cindex @code{maskload@var{m}@var{n}} instruction pattern
 @item @samp{maskload@var{m}@var{n}}
 Perform a masked load of vector from memory operand 1 of mode @var{m}
-into register operand 0.  Mask is provided in register operand 2 of
-mode @var{n}.
+into register operand 0.  The mask is provided in register operand 2 of
+mode @var{n}.  Operand 3 (the "else value") specifies which value is loaded
+when the mask is unset.  The predicate of operand 3 must only accept
+the else values that the target actually supports.  Currently two values
+are attempted, zero and undefined.  GCC handles an else value of zero more
+efficiently than an undefined one.
 
 This pattern is not allowed to @code{FAIL}.
 
@@ -5435,15 +5450,16 @@  Operands 0 and 1 have mode @var{m}, which must be a vector mode.  Operand 3
 has whichever integer mode the target prefers.  A mask is specified in
 operand 2 which must be of type @var{n}.  The mask has lower precedence than
 the length and is itself subject to length masking,
-i.e. only mask indices < (operand 3 + operand 4) are used.
+i.e. only mask indices < (operand 4 + operand 5) are used.
+Operand 3 is an else operand similar to the one in @code{maskload}.
 Operand 4 conceptually has mode @code{QI}.
 
-Operand 2 can be a variable or a constant amount.  Operand 4 specifies a
+Operand 2 can be a variable or a constant amount.  Operand 5 specifies a
 constant bias: it is either a constant 0 or a constant -1.  The predicate on
-operand 4 must only accept the bias values that the target actually supports.
+operand 5 must only accept the bias values that the target actually supports.
 GCC handles a bias of 0 more efficiently than a bias of -1.
 
-If (operand 2 + operand 4) exceeds the number of elements in mode
+If (operand 2 + operand 4 + operand 5) exceeds the number of elements in mode
 @var{m}, the behavior is undefined.
 
 If the target prefers the length to be measured in bytes