Add support for specialization constants by ndgrigorian · Pull Request #2304 · IntelPython/dpctl

ndgrigorian · 2026-04-28T22:44:35Z

This PR introduces support for specialization constants in dpctl, including both a Cython class SpecializationConstant for construction and passing of the constructed class to create_kernel_bundle_from_spirv via a new specializations keyword argument.

The SpecializationConstant class supports multiple constructors, including from Python buffers, a dtype string and a Python buffer (casting to the dtype via NumPy), and a number of bytes and a pointer as integers.

Also introduces dpctl.program.utils with parse_spirv_specializations utility function, allowing the user to query a SPIR-V directly from Python.

Have you provided a meaningful PR description?
Have you added a test, reproducer or referred to an issue with a reproducer?
Have you tested your changes locally for CPU and GPU devices?
Have you made sure that new changes do not introduce compiler warnings?
Have you checked performance impact of proposed changes?
Have you added documentation for your changes, if necessary?
Have you added your changes to the changelog?
If this PR is a work in progress, are you opening the PR as a draft?

github-actions · 2026-04-28T22:48:35Z

View rendered docs @ https://intelpython.github.io/dpctl/pulls/2304/index.html

coveralls · 2026-04-28T23:31:41Z

coverage: 75.295% (-0.1%) from 75.39% — feature/specialization-constants into master

antonwolfy · 2026-05-22T07:28:54Z

@@ -0,0 +1,25 @@
+#                      Data Parallel Control (dpctl)
+#
+# Copyright 2020-2025 Intel Corporation


It seems we need to update the copyright year everywhere in dpctl

antonwolfy · 2026-05-22T07:30:40Z

+    spv_bytes: bytes | bytearray | memoryview,
+) -> tuple[SpecializationConstantInfo]:
+    """
+    Parses SPIR-V byte stream to extract information about specializations,


Needs to add rendering documentation for the new functions

antonwolfy · 2026-05-22T07:44:39Z

+
+
+class SpirvOpCode(IntEnum):
+    OpName = 5


I wonder if it makes sense to import the interesting constants directly from the SPIRV-Headers?
Or probably to add just a ref comment with a link to the code from where the constants come?

there's no wheel package on PyPI for SPIRV-headers, which is why this wasn't done. In theory there is already spirv-dis which disassembles SPIRV and can be used to get some of the info, but for that same reason this wasn't done

A link makes sense in the ref though

antonwolfy · 2026-05-22T07:54:40Z

+            }
+        }
+        else {
+            error_handler("clSetProgramSpecializationConstant is not available "


Missing to release clProgram on error

antonwolfy · 2026-05-22T08:01:50Z

+
+        if word_count == 0:
+            raise ValueError(f"Invalid SPIR-V instruction at word index {i}")
+


Missing boundary check:

if i + word_count > len(words): raise ValueError(f"Invalid SPIR-V: instruction at offset {i} extends beyond buffer")

antonwolfy · 2026-05-22T08:05:06Z

+                )
+            elif isinstance(args[0], str):
+                target_obj = np.ascontiguousarray(args[1], dtype=args[0])
+


Do we need an explicit error handling here in case of else?

antonwolfy · 2026-05-22T08:06:38Z

+                # attempt to coerce to a numpy array
+                target_obj = np.ascontiguousarray(target_obj)
+        else:
+            raise TypeError(


Probably it'd better to move raise TypeError(...) here from line 335, otherwise that branch is unreachable.

antonwolfy · 2026-05-22T08:07:37Z

@@ -444,8 +480,22 @@ _CreateKernelBundleWithIL_ze_impl(const context &SyclCtx,
    ZeDevice = get_native<ze_be>(SyclDev);

    // Specialization constants are not supported by DPCTL at the moment


Is the comment obsolete now?

yep, good catch

antonwolfy · 2026-05-22T08:18:27Z

+
+        dtype_str = type_info["dtype"]
+        raw_default = defaults.get(target_id)
+        default_value = None


It seems when raw_default is True or False (from OpSpecConstantTrue/OpSpecConstantFalse at lines 141, 146), the default value is not set in the result. Is that intended?

antonwolfy · 2026-05-22T08:20:28Z

+      the second argument is interpreted as a pointer to the data.
+
+    Note that when constructing from a buffer, the
+    :class:`.SpecializationConstant`, shares memory with the original object.


We probably need to warn also about object lifetime: if the source object is deleted, the SpecializationConstant holds a dangling pointer.

also removes "v" as a permitted specialization constant intermediate data type, as composite specialization constants are broken into multiple specialization constants, so structs end up passed as a single constant while the program expects multiple, and therefore, doesn't work as intended

also adds spec_id, itemsize, and default_value fields

ndgrigorian changed the title ~~Feature/specialization constants~~ Add support for specialization constants Apr 28, 2026

ndgrigorian force-pushed the feature/specialization-constants branch 3 times, most recently from b7f8d82 to 8c5651d Compare May 5, 2026 06:23

ndgrigorian marked this pull request as ready for review May 5, 2026 06:28

ndgrigorian requested review from antonwolfy and vlad-perevezentsev as code owners May 5, 2026 06:28

ndgrigorian force-pushed the feature/specialization-constants branch 3 times, most recently from 8dbb320 to 043aa83 Compare May 5, 2026 06:52

ndgrigorian force-pushed the rename-sycl-program-sycl-kernel-bundle branch from 82736b8 to 1a0a910 Compare May 7, 2026 01:12

ndgrigorian force-pushed the feature/specialization-constants branch from 55d4458 to 97871d9 Compare May 7, 2026 01:12

Base automatically changed from rename-sycl-program-sycl-kernel-bundle to master May 21, 2026 17:11

antonwolfy reviewed May 22, 2026

View reviewed changes

ndgrigorian added 7 commits May 23, 2026 18:07

Implement SpecializationConstant class

7946152

hook specialization constants into kernel bundle interface

b5befc3

add test for SpecializationConstant use in kernel

8ddc440

fix libsyclinterface tests

9e264f2

add program.utils namespace with SPIRV parser

b100cf5

Refactor specialiazation constants to use dataclass

e2e4826

also adds spec_id, itemsize, and default_value fields

ndgrigorian force-pushed the feature/specialization-constants branch from 97871d9 to e2e4826 Compare May 24, 2026 01:07


		if word_count == 0:
		raise ValueError(f"Invalid SPIR-V instruction at word index {i}")

		@@ -444,8 +480,22 @@ _CreateKernelBundleWithIL_ze_impl(const context &SyclCtx,
		ZeDevice = get_native<ze_be>(SyclDev);

		// Specialization constants are not supported by DPCTL at the moment

Conversation

ndgrigorian commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 28, 2026

Uh oh!

coveralls commented Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ndgrigorian commented Apr 28, 2026 •

edited

Loading

coveralls commented Apr 28, 2026 •

edited

Loading