https://gcc.gnu.org/g:82504fd60da7dd2cd31a3ce0feb0d960f9270913
commit r17-6093-g82504fd60da7dd2cd31a3ce0feb0d960f9270913 Author: Kyrylo Tkachov <[email protected]> Date: Mon Nov 9 10:47:56 2026 +0100 doc: Document the clmul and clmul_widen optabs [PR128111] The clmul and clmul_widen optabs were added together with __builtin_clmulg but are not described in md.texi. Document the operand order, the semantics and that the patterns may FAIL. gcc/ChangeLog: PR middle-end/128111 * doc/md.texi (clmul@var{m}3, clmul_widen@var{m}3): Document. Signed-off-by: Kyrylo Tkachov <[email protected]> Diff: --- gcc/doc/md.texi | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/gcc/doc/md.texi b/gcc/doc/md.texi index 921f7623be41..0697d517dbf1 100644 --- a/gcc/doc/md.texi +++ b/gcc/doc/md.texi @@ -5363,6 +5363,47 @@ Reverse the order of bytes of operand 1 and store the result in operand 0. @item @samp{bitreverse@var{m}2} Reverse the order of bits of operand 1 and store the result in operand 0. +@mdindex clmul@var{m}3 +@item @samp{clmul@var{m}3} +Perform carry-less multiplication of operands 1 and 2 and store the +least significant bits of the result, which have the same width as +the operands, in operand 0. All three operands have the same scalar +integer mode @var{m}, and the operands are treated as unsigned. +This is equivalent to the C code: +@smallexample +unsigned_type r = 0; +for (int i = 0; i < width; i++) + if ((op2 >> i) & 1) + r ^= op1 << i; +op0 = r; +@end smallexample +where @code{width} is the bit size of mode @var{m}. A pattern in +mode @var{m} is also used for narrower operations, by zero extending +the operands to mode @var{m}. + +@mdindex clmul_widen@var{m}3 +@item @samp{clmul_widen@var{m}3} +Perform carry-less multiplication of operands 2 and 3, which have +mode @var{m}, and store the least significant half of the full +product in operand 0 and the most significant half in operand 1. +All four operands have the same scalar integer mode @var{m}, and the +inputs are treated as unsigned. This is equivalent to the C code: +@smallexample +wide_type r = 0; +for (int i = 0; i < width; i++) + if ((op3 >> i) & 1) + r ^= (wide_type) op2 << i; +op0 = (narrow_type) r; +op1 = (narrow_type) (r >> width); +@end smallexample +where @code{wide_type} has twice the precision of @code{narrow_type} +and @code{width} is the bit size of mode @var{m}. This is used to +expand the three argument form of @code{__builtin_clmulg}. + +Neither @samp{clmul@var{m}3} nor @samp{clmul_widen@var{m}3} has to +handle all operand values. They may @code{FAIL}, in which case the +compiler falls back to another expansion. + @mdindex neg@var{m}2 @mdindex ssneg@var{m}2 @mdindex usneg@var{m}2
