doc: postops: update docs to describe binary select postop

avmanerikar · avmanerikar · commit cec796cc28ec · 2025-04-10T09:14:43.000-07:00
diff --git a/doc/primitives/binary.md b/doc/primitives/binary.md
@@ -42,7 +42,8 @@ argument index as specified by the following table.
 | \f$\src_1\f$                | DNNL_ARG_SRC_1                                                            |
 | \f$\src_2\f$                | DNNL_ARG_SRC_2                                                            |
 | \dst                        | DNNL_ARG_DST                                                              |
-| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1 |
+| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1,|
+|                             | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_2 |
 | \f$binary scale0\f$         | DNNL_ARG_ATTR_SCALES \| DNNL_ARG_SRC_0                                    |
 | \f$binary scale1\f$         | DNNL_ARG_ATTR_SCALES \| DNNL_ARG_SRC_1                                    |
 
diff --git a/doc/primitives/convolution.md b/doc/primitives/convolution.md
@@ -152,7 +152,8 @@ argument index as specified by the following table.
 | \diffbias                   | DNNL_ARG_DIFF_BIAS                                                         |
 | \diffdst                    | DNNL_ARG_DIFF_DST                                                          |
 | \f$depthwise\f$             | DNNL_ARG_ATTR_POST_OP_DW                                                   |
-| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1  |
+| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1, |
+|                             | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_2  |
 | \f$\text{prelu post-op}\f$  | DNNL_ARG_ATTR_MULTIPLE_POST_OP(prelu_post_op_position) \| DNNL_ARG_WEIGHTS |
 
 ## Implementation Details
diff --git a/doc/primitives/eltwise.md b/doc/primitives/eltwise.md
@@ -84,7 +84,8 @@ argument index as specified by the following table.
 | \dst                        | DNNL_ARG_DST                                                              |
 | \diffsrc                    | DNNL_ARG_DIFF_SRC                                                         |
 | \diffdst                    | DNNL_ARG_DIFF_DST                                                         |
-| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1 |
+| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1,|
+|                             | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_2 |
 
 ## Implementation Details
 
diff --git a/doc/primitives/group_normalization.md b/doc/primitives/group_normalization.md
@@ -109,7 +109,8 @@ argument index as specified by the following table.
 | \diffsrc                    | DNNL_ARG_DIFF_SRC                                                         |
 | \f$\diffgamma\f$            | DNNL_ARG_DIFF_SCALE                                                       |
 | \f$\diffbeta\f$             | DNNL_ARG_DIFF_SHIFT                                                       |
-| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1 |
+| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1,|
+|                             | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_2 |
 
 ## Implementation Details
 
diff --git a/doc/primitives/inner_product.md b/doc/primitives/inner_product.md
@@ -59,7 +59,8 @@ argument index as specified by the following table.
 | \diffweights                | DNNL_ARG_DIFF_WEIGHTS                                                      |
 | \diffbias                   | DNNL_ARG_DIFF_BIAS                                                         |
 | \diffdst                    | DNNL_ARG_DIFF_DST                                                          |
-| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1  |
+| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1, |
+|                             | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_2  |
 | \f$\text{prelu post-op}\f$  | DNNL_ARG_ATTR_MULTIPLE_POST_OP(prelu_post_op_position) \| DNNL_ARG_WEIGHTS |
 
 ## Implementation Details
diff --git a/doc/primitives/layer_normalization.md b/doc/primitives/layer_normalization.md
@@ -99,8 +99,8 @@ argument index as specified by the following table.
 | \diffbeta                   | DNNL_ARG_DIFF_SHIFT                                                       |
 | \f$src scale\f$             | DNNL_ARG_ATTR_SCALES \| DNNL_ARG_SRC                                      |
 | \f$dst scale\f$             | DNNL_ARG_ATTR_SCALES \| DNNL_ARG_DST                                      |
-| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1 |
-
+| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1,|
+|                             | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_2 |
 
 ## Implementation Details
 
diff --git a/doc/primitives/matmul.md b/doc/primitives/matmul.md
@@ -53,7 +53,8 @@ argument index as specified by the following table.
 | \f$\text{dropout output mask}\f$ | DNNL_ARG_ATTR_DROPOUT_MASK                                                 |
 | \f$\text{dropout probability}\f$ | DNNL_ARG_ATTR_DROPOUT_PROBABILITY                                          |
 | \f$\text{dropout rng seed}\f$    | DNNL_ARG_ATTR_DROPOUT_SEED                                                 |
-| \f$\text{binary post-op}\f$      | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1  |
+| \f$\text{binary post-op}\f$      | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1, |
+|                                  | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_2  |
 | \f$\text{prelu post-op}\f$       | DNNL_ARG_ATTR_MULTIPLE_POST_OP(prelu_post_op_position) \| DNNL_ARG_WEIGHTS |
 
 ## Implementation Details
diff --git a/doc/primitives/pooling.md b/doc/primitives/pooling.md
@@ -68,7 +68,8 @@ argument index as specified by the following table.
 | workspace                   | DNNL_ARG_WORKSPACE                                                        |
 | \diffsrc                    | DNNL_ARG_DIFF_SRC                                                         |
 | \diffdst                    | DNNL_ARG_DIFF_DST                                                         |
-| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1 |
+| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1,|
+|                             | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_2 |
 
 ## Implementation Details
 
diff --git a/doc/primitives/reduction.md b/doc/primitives/reduction.md
@@ -59,7 +59,8 @@ argument index as specified by the following table.
 |-----------------------------|---------------------------------------------------------------------------|
 | \src                        | DNNL_ARG_SRC                                                              |
 | \dst                        | DNNL_ARG_DST                                                              |
-| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1 |
+| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1,|
+|                             | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_2 |
 
 ## Implementation Details
 
diff --git a/doc/primitives/resampling.md b/doc/primitives/resampling.md
@@ -90,7 +90,8 @@ argument index as specified by the following table.
 | \dst                        | DNNL_ARG_DST                                                              |
 | \diffsrc                    | DNNL_ARG_DIFF_SRC                                                         |
 | \diffdst                    | DNNL_ARG_DIFF_DST                                                         |
-| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1 |
+| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1,|
+|                             | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_2 |
 
 ## Implementation Details
 
diff --git a/doc/primitives/softmax.md b/doc/primitives/softmax.md
@@ -82,7 +82,8 @@ argument index as specified by the following table.
 | \diffdst                    | DNNL_ARG_DIFF_DST                                                         |
 | \f$src scale\f$             | DNNL_ARG_ATTR_SCALES \| DNNL_ARG_SRC                                      |
 | \f$dst scale\f$             | DNNL_ARG_ATTR_SCALES \| DNNL_ARG_DST                                      |
-| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1 |
+| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1,|
+|                             | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_2 |
 
 ## Implementation Details
 
diff --git a/doc/programming_model/attributes_post_ops.md b/doc/programming_model/attributes_post_ops.md
@@ -281,6 +281,29 @@ Currently the following scenarios are optimized:
   post-operation which format may be queried from attributes using
   `dnnl::post_ops::get_params_binary(...)` function call.
 
+For the binary select operation, an additional conditional tensor is required 
+to execute the operation which is implemented using:
+
+~~~cpp
+void dnnl::post_ops::append_binary(
+        algorithm alg, // binary algorithm to apply
+        const memory::desc &src1 // memory descriptor for a second memory operand
+        const memory::desc &src2 // memory descriptor for a third memory operand
+        );
+~~~
+
+The `alg`, `src1` and `src2` parameters are the same as in 
+@ref dev_guide_binary.
+
+The binary post-op thus becomes:
+
+\f[
+    \dst[:] = \operatorname{binary}(\operatorname{Op}(...), Source\_1[:], Source\_2[:])
+\f]
+
+There is no broadcasting support for the conditional tensor. The select op is only 
+supported for CPU implementations.
+
 @anchor dev_guide_attributes_post_ops_prelu
 ### Prelu Post-op
 
diff --git a/tests/benchdnn/doc/knobs_attr.md b/tests/benchdnn/doc/knobs_attr.md
@@ -249,6 +249,7 @@ supported, positioned after `MASK_INPUT`, to specify physical memory format.
 - `mul`
 - `ne`
 - `sub`
+- `select`
 
 ### Prelu
 `PRELU` post operation kind applies forward algorithm to the operations result
