Hi all,
Following the discussion here:
https://gcc.gnu.org/pipermail/gcc-patches/2026-May/716769.html
this expands the internal function documentation for IFN_MASK_LOAD to
spell out the signature of the function and explain how it relates to
the optab.
The purpose of this RFC is mostly to agree on a style for documenting
IFNs in general, I just picked IFN_MASK_LOAD as it was a non-trivial
example that I am somewhat familiar with.
As richi suggested, it also adds a clickable reference to the
corresponding optab documentation.
Tested by building the html docs and eyeballing in a browser (checking
that the cross-reference works).
Thoughts? If this style is OK, is it OK to commit and flesh out the
other entries incrementally?
Thanks,
Alex
gcc/ChangeLog:
* doc/ifn.texi (Direct Internal Functions): Flesh out
documentation for IFN_MASK_LOAD.
* doc/md.texi (Standard Names): Add anchor for maskloadmn so it
can be cross-referenced.
diff --git a/gcc/doc/ifn.texi b/gcc/doc/ifn.texi
index 6d1c190b5b1..95813a26473 100644
--- a/gcc/doc/ifn.texi
+++ b/gcc/doc/ifn.texi
@@ -63,8 +63,19 @@ instruction pattern.
@cindex @code{IFN_MASK_LOAD} internal function
@item @samp{IFN_MASK_LOAD}
-The @code{IFN_MASK_LOAD} internal function directly maps to the @code{maskload}
-instruction pattern.
+The @code{IFN_MASK_LOAD} internal function maps directly to the
+@code{maskload} instruction pattern (@pxref{maskload@var{m}@var{n}}).
+For a vector type @code{v} (with @code{TYPE_MODE} @var{m}), a mask type
+@code{p} (with @code{TYPE_MODE} @var{n}), and pointer type
+@code{aliasptr}, the signature of the internal function is:
+@smallexample
+v IFN_MASK_LOAD (v *addr, aliasptr cookie, p mask, v elseval)
+@end smallexample
+a call to this internal function with lhs @var{r} maps to
+@code{maskload@var{m}@var{n}} with the following operands array:
+@code{[@var{r}, addr, mask, elseval]}. @code{cookie}'s type
+(@code{aliasptr}) is a pointer type used for type-based alias analysis,
+and its value gives the alignment of the load in bits.
@cindex @code{IFN_LOAD_LANES} internal function
@item @samp{IFN_LOAD_LANES}
diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi
index 94d258c3c91..1e3ab889e66 100644
--- a/gcc/doc/md.texi
+++ b/gcc/doc/md.texi
@@ -7617,6 +7617,7 @@ Operands 0, 2 and 3 have mode @var{m}. Operand 1 has
mode @var{n}.
Operands 4 and 5 have a target-dependent scalar integer mode.
@mdindex maskload@var{m}@var{n}
+@anchor{maskload@var{m}@var{n}}
@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. The mask is provided in register operand 2 of
