[DSLX Fuzz Testing] Fixed support for specifying domains of tuple parameters in fuzz tests.

FuzzTest unpacks `TupleOf` domains for free functions, causing a signature mismatch when the function expects a single tuple argument. This was fixed by:
- Wrapping top-level tuple domains in an extra `fuzztest::TupleOf(...)`.
- Generating C++ `std::tuple` for tuple parameters in the property function signature.
- Generating recursive conversion logic to `xls::Value` in the property function body.

Also, updated the catalog of examples in `fuzz_test_domains.x` and documented the solution in `README.md`.

PiperOrigin-RevId: 913885815

Author: dplassgit

xls/jit/fuzztest_cc.tmpl

@@ -22,13 +22,13 @@ void {{fuzztest.property_function_name}}({% for param in fuzztest.params %}{{par
   {% else %}
   // Fallback: Manual binding for the standard Run(xls::Value...) overload.
   {% for param in fuzztest.params %}
-  {% if param.is_native %}
+  {% if param.conversion_snippet %}
   xls::Value {{param.name}}_val = {{param.conversion_snippet}};
   {% endif %}
   {% endfor %}
   XLS_ASSERT_OK_AND_ASSIGN(xls::Value result, f->Run(
   {% for param in fuzztest.params %}
-  {{param.name}}{% if param.is_native %}_val{% endif %}{% if not loop.last %}, {% endif %}
+  {{param.name}}{% if param.conversion_snippet %}_val{% endif %}{% if not loop.last %}, {% endif %}
   {% endfor %}
   ));
   {% endif %}

xls/jit/jit_wrapper_generator.py

@@ -386,6 +386,23 @@ def to_domain(
   raise app.UsageError(f"Unsupported domain: {d}")
 
 
+def to_value_conversion(t: type_pb2.TypeProto, expr: str) -> str:
+  """Generates C++ snippet to convert a native type to xls::Value."""
+  if t.type_enum == type_pb2.TypeProto.BITS:
+    return f"xls::Value(xls::UBits({expr}, {t.bit_count}))"
+  elif t.type_enum == type_pb2.TypeProto.TUPLE:
+    elems = []
+    for i, e in enumerate(t.tuple_elements):
+      elems.append(to_value_conversion(e, f"std::get<{i}>({expr})"))
+    return f"xls::Value::Tuple({{{', '.join(elems)}}})"
+  elif t.type_enum == type_pb2.TypeProto.ARRAY:
+    elems = []
+    for i in range(t.array_size):
+      elems.append(to_value_conversion(t.array_element, f"{expr}[{i}]"))
+    return f"xls::Value::Array({{{', '.join(elems)}}})"
+  raise app.UsageError(f"Unsupported type for value conversion: {t}")
+
+
 def to_chan(
     c: ir_interface_pb2.PackageInterfaceProto.Channel, package_name: str
 ) -> XlsChannel:
@@ -592,9 +609,6 @@ def wrapped_to_fuzztest(
   if wrapped.params:
     for idx, p in enumerate(wrapped.params):
       is_native = p.specialized_type is not None
-      cpp_type = p.specialized_type or "xls::Value"
-      conversion_snippet = None
-
       domain_proto = p.fuzztest_info.domain_proto if p.fuzztest_info else None
       domain_snippet = (
           p.fuzztest_info.domain_snippet if p.fuzztest_info else None
@@ -603,11 +617,16 @@ def wrapped_to_fuzztest(
       if not is_native and can_use_uint64_range(p.type_proto, domain_proto):
         cpp_type = "uint64_t"
         is_native = True
+      else:
+        cpp_type = to_c_type(p.type_proto)
 
-      if is_native and p.type_proto.type_enum == type_pb2.TypeProto.BITS:
-        conversion_snippet = (
-            f"xls::Value(xls::UBits({p.name}, {p.type_proto.bit_count}))"
-        )
+      conversion_snippet = to_value_conversion(p.type_proto, p.name)
+
+      if (
+          p.type_proto.type_enum == type_pb2.TypeProto.TUPLE
+          and domain_snippet is not None
+      ):
+        domain_snippet = f"fuzztest::TupleOf({domain_snippet})"
 
       params.append(
           PropertyFunctionParam(

xls/jit/jit_wrapper_generator_test.py

@@ -294,6 +294,12 @@ def test_function_tuple_param(self):
                 packed_type='',
                 unpacked_type='',
                 specialized_type=None,
+                fuzztest_info=jit_wrapper_generator.FuzzTestInfo(
+                    domain_snippet=(
+                        'fuzztest::TupleOf(fuzztest::Arbitrary<uint8_t>(),'
+                        ' fuzztest::Arbitrary<uint64_t>())'
+                    )
+                ),
             ),
         ],
         result=jit_wrapper_generator.XlsNamedValue(
@@ -312,6 +318,14 @@ def test_function_tuple_param(self):
     self.assertLen(prop_func.params, 1)
     self.assertEqual(prop_func.params[0].name, 't')
     self.assertEqual(prop_func.params[0].index, 0)
+    self.assertEqual(
+        prop_func.params[0].cpp_type, 'std::tuple<uint8_t, uint64_t>'
+    )
+    self.assertEqual(
+        prop_func.params[0].domain_snippet,
+        'fuzztest::TupleOf(fuzztest::TupleOf(fuzztest::Arbitrary<uint8_t>(),'
+        ' fuzztest::Arbitrary<uint64_t>()))',
+    )
 
   def test_function_no_result(self):
     u8 = type_pb2.TypeProto(type_enum=type_pb2.TypeProto.BITS, bit_count=8)
@@ -344,6 +358,72 @@ def test_function_no_result(self):
     self.assertEqual(prop_func.params[0].name, 'a')
 
 
+class JitWrapperGeneratorToValueConversionTest(absltest.TestCase):
+
+  def test_bits(self):
+    u32 = type_pb2.TypeProto(type_enum=type_pb2.TypeProto.BITS, bit_count=32)
+    self.assertEqual(
+        jit_wrapper_generator.to_value_conversion(u32, 'x'),
+        'xls::Value(xls::UBits(x, 32))',
+    )
+
+  def test_tuple_of_tuples(self):
+    u8 = type_pb2.TypeProto(type_enum=type_pb2.TypeProto.BITS, bit_count=8)
+    inner_tup = type_pb2.TypeProto(
+        type_enum=type_pb2.TypeProto.TUPLE, tuple_elements=[u8]
+    )
+    outer_tup = type_pb2.TypeProto(
+        type_enum=type_pb2.TypeProto.TUPLE, tuple_elements=[inner_tup]
+    )
+    self.assertEqual(
+        jit_wrapper_generator.to_value_conversion(outer_tup, 't'),
+        'xls::Value::Tuple({xls::Value::Tuple({xls::Value(xls::UBits('
+        'std::get<0>(std::get<0>(t)), 8))})})',
+    )
+
+  def test_tuple_of_arrays(self):
+    u8 = type_pb2.TypeProto(type_enum=type_pb2.TypeProto.BITS, bit_count=8)
+    a8 = type_pb2.TypeProto(
+        type_enum=type_pb2.TypeProto.ARRAY, array_size=2, array_element=u8
+    )
+    tup = type_pb2.TypeProto(
+        type_enum=type_pb2.TypeProto.TUPLE, tuple_elements=[a8]
+    )
+    self.assertEqual(
+        jit_wrapper_generator.to_value_conversion(tup, 't'),
+        'xls::Value::Tuple({xls::Value::Array({xls::Value(xls::UBits('
+        'std::get<0>(t)[0], 8)), xls::Value(xls::UBits(std::get<0>(t)[1], 8))})'
+        '})',
+    )
+
+  def test_tuple_of_primitives(self):
+    u8 = type_pb2.TypeProto(type_enum=type_pb2.TypeProto.BITS, bit_count=8)
+    u32 = type_pb2.TypeProto(type_enum=type_pb2.TypeProto.BITS, bit_count=32)
+    tup = type_pb2.TypeProto(
+        type_enum=type_pb2.TypeProto.TUPLE, tuple_elements=[u8, u32]
+    )
+    self.assertEqual(
+        jit_wrapper_generator.to_value_conversion(tup, 't'),
+        'xls::Value::Tuple({xls::Value(xls::UBits(std::get<0>(t), 8)),'
+        ' xls::Value(xls::UBits(std::get<1>(t), 32))})',
+    )
+
+  def test_mixed_tuple(self):
+    u8 = type_pb2.TypeProto(type_enum=type_pb2.TypeProto.BITS, bit_count=8)
+    u32 = type_pb2.TypeProto(type_enum=type_pb2.TypeProto.BITS, bit_count=32)
+    a8 = type_pb2.TypeProto(
+        type_enum=type_pb2.TypeProto.ARRAY, array_size=1, array_element=u8
+    )
+    tup = type_pb2.TypeProto(
+        type_enum=type_pb2.TypeProto.TUPLE, tuple_elements=[u32, a8]
+    )
+    self.assertEqual(
+        jit_wrapper_generator.to_value_conversion(tup, 't'),
+        'xls::Value::Tuple({xls::Value(xls::UBits(std::get<0>(t), 32)),'
+        ' xls::Value::Array({xls::Value(xls::UBits(std::get<1>(t)[0], 8))})})',
+    )
+
+
 class JitWrapperGeneratorRenderFuzztestTest(absltest.TestCase):
 
   def setUp(self):
@@ -396,7 +476,7 @@ def test_render_fuzztest_basic(self):
         'xls::test::MyFuncJit',
         'my_func_jit.h',
     )
-    self.assertIn('void my_func(xls::Value a, xls::Value b)', rendered_code)
+    self.assertIn('void my_func(uint8_t a, uint32_t b)', rendered_code)
     self.assertIn(
         'XLS_ASSERT_OK_AND_ASSIGN(xls::Value result, f->Run(', rendered_code
     )
@@ -441,7 +521,9 @@ def test_render_fuzztest_array_of_int(self):
         'xls::test::ArrayIntFuncJit',
         'array_int_func_jit.h',
     )
-    self.assertIn('void array_int_func(xls::Value x)', rendered_code)
+    self.assertIn(
+        'void array_int_func(std::array<uint16_t, 4> x)', rendered_code
+    )
     self.assertIn(
         'FUZZ_TEST(array_int_func_fuzztest, array_int_func)', rendered_code
     )
@@ -483,7 +565,10 @@ def test_render_fuzztest_array_of_tuple(self):
         'xls::test::ArrayTupleFuncJit',
         'array_tuple_func_jit.h',
     )
-    self.assertIn('void array_tuple_func(xls::Value y)', rendered_code)
+    self.assertIn(
+        'void array_tuple_func(std::array<std::tuple<uint8_t, uint32_t>, 3> y)',
+        rendered_code,
+    )
     self.assertIn(
         'FUZZ_TEST(array_tuple_func_fuzztest, array_tuple_func)', rendered_code
     )
@@ -524,7 +609,9 @@ def test_render_fuzztest_tuple_of_int(self):
         'xls::test::TupleIntFuncJit',
         'tuple_int_func_jit.h',
     )
-    self.assertIn('void tuple_int_func(xls::Value t)', rendered_code)
+    self.assertIn(
+        'void tuple_int_func(std::tuple<uint16_t, uint64_t> t)', rendered_code
+    )
     self.assertIn(
         'FUZZ_TEST(tuple_int_func_fuzztest, tuple_int_func)', rendered_code
     )
@@ -569,7 +656,11 @@ def test_render_fuzztest_tuple_mixed(self):
         'xls::test::TupleMixedFuncJit',
         'tuple_mixed_func_jit.h',
     )
-    self.assertIn('void tuple_mixed_func(xls::Value m)', rendered_code)
+    self.assertIn(
+        'void tuple_mixed_func(std::tuple<uint8_t, std::tuple<uint8_t,'
+        ' uint16_t>> m)',
+        rendered_code,
+    )
     self.assertIn(
         'FUZZ_TEST(tuple_mixed_func_fuzztest, tuple_mixed_func)', rendered_code
     )
@@ -607,7 +698,7 @@ def test_render_fuzztest_uses_property_param_filter(self):
         'xls::test::MyFuncJit',
         'my_func_jit.h',
     )
-    self.assertEqual(rendered_code, 'const xls::Value& a')
+    self.assertEqual(rendered_code, 'uint8_t a')
 
   def test_render_fuzztest_default_domain(self):
     u32 = type_pb2.TypeProto(type_enum=type_pb2.TypeProto.BITS, bit_count=32)

xls/tests/fuzz_test/BUILD

@@ -35,6 +35,12 @@ dslx_fuzz_test(
     test_function = "test_arbitrary",
 )
 
+dslx_fuzz_test(
+    name = "test_no_domains_fuzz_test",
+    library = ":fuzz_test_dslx",
+    test_function = "test_no_domains",
+)
+
 dslx_fuzz_test(
     name = "test_arbitrary_opt_fuzz_test",
     library = ":fuzz_test_dslx",
@@ -53,3 +59,9 @@ dslx_fuzz_test(
     library = ":fuzz_test_dslx",
     test_function = "test_element_of",
 )
+
+dslx_fuzz_test(
+    name = "test_tuple_fuzz_test",
+    library = ":fuzz_test_dslx",
+    test_function = "test_tuple",
+)

xls/tests/fuzz_test/README.md

@@ -9,17 +9,19 @@ the `#[fuzz_test]` attribute:
 
 -   **Arbitrary**: `()` - Explores the full range of the type.
 -   **Numeric Range**: `Type:min..max` - Explores values in the range `[min,
-    max)`. Example: `u32:0..100`.
+    max)`. Example: `u32:0..100`. "End-inclusive" ranges work too, e.g.,
+    `Type:min..=max` explores values in the range `[min, max]`.
 -   **Element Of**: `[val1, val2, ...]` - Explores only the listed values.
     Example: `[u32:5, 10, 15]`.
+-   **Tuples**: `(Domain1, Domain2, ...)` - For tuple parameters. Example:
+    `(u32:0..10, [u8:1, 2])`. The parentheses are required.
 
 ## Known Limitations
 
 -   **Array parameters**: `(ElementDomain)[N]` is not yet supported; however if
-    you specify the parameter as arbitrary (i.e., `()`) it will Just Work.
+    you specify the parameter "as arbitrary" (i.e., `()`) it will Just Work.
 -   **Struct parameters**: `StructName { field: Domain, ... }` is not yet
     supported.
--   **Tuple parameters**: `(Domain1, Domain2, ...)` is not yet supported.
 -   Fuzzing is currently limited to types that can be mapped to native C++ types
     up to 64 bits for full specialization. Larger types fallback to `xls::Value`
     and may have limited mutation capabilities.

xls/tests/fuzz_test/fuzz_tests.x

@@ -12,6 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// No domain attribute is the same as #[fuzz_test(domains=`()`)]
+fn test_no_domains(x: u32) -> bool { x == x }
+
 #[fuzz_test(domains=`()`)]
 fn test_arbitrary(x: u32) -> bool {
     x == x
@@ -26,3 +29,8 @@ fn test_range(x: u32) -> bool {
 fn test_element_of(x: u32) -> bool {
     x == u32:5 || x == u32:10 || x == u32:15
 }
+
+#[fuzz_test(domains=`(u32:0..10, [u8:1, 2])`)]
+fn test_tuple(t: (u32, u8)) -> bool {
+    t.0 <= u32:10 && (t.1 == u8:1 || t.1 == u8:2)
+}