v_opencl_bindings

Project portfolio

Generates V bindings for OpenCL from the canonical Khronos cl.xml registry.

The generated module is published as antono2.opencl on VPM.

v install antono2.opencl

Maintainers can prepare a checkout on every supported operating system with v run setup.vsh; use v run setup.vsh --check for read-only diagnostics. Each synchronized antono2.opencl release includes its own end-user setup script for installing the loader, headers, and a development runtime.

The complete OpenCL 1.0 through 3.0 core constant surface, including bitfields and error codes, is read directly from the registry rather than maintained as duplicated values. Constants retain the corresponding OpenCL typedef as their V type. OpenCL 1.0 through 3.0 scalar aliases, opaque handles, and structures are selected from the feature requirements and generated by resolving their XML typedef chains to V ABI types. OpenCL 1.0 through 3.0 command declarations and inline V wrappers are generated from cumulative feature requirements, including pointer depth, opaque handles, callbacks, return types, and acronym-aware snake-case function names. The seven distinct callback ABIs used by core commands are exposed as named V function types rather than untyped pointers. REGISTRY_COMMIT and HEADERS_COMMIT record the immutable Khronos inputs used for generation and ABI validation. The OpenCL 1.2 cl_image_desc anonymous union is emitted as its ABI-equivalent Mem field because both C union alternatives have the same handle type.

Generate

Prepare both pinned Khronos checkouts and validate the generator with one cross-platform command:

v run setup.vsh

Use v run setup.vsh --check to verify tools and revisions without changing the checkouts or generated source.

git clone --depth 1 https://github.com/KhronosGroup/OpenCL-Docs.git opencldocs
python3 src/main.py -registry opencldocs/xml/cl.xml opencl.v
v fmt -w src/opencl.v

v_opencl_bindings is the canonical source for generated bindings, hand-written convenience code, ABI probes, and examples. Run python3 tools/sync_published_module.py ../opencl --check to detect drift or omit --check to synchronize a checkout. The publication workflow opens an antono2/opencl pull request when the repository secret OPENCL_PUBLISH_TOKEN has cross-repository contents and pull-request access. The published module's GENERATOR_COMMIT records the exact commit synchronized by that workflow so a release can be traced back to its canonical source. VERSION, the published module's v.mod version, and LICENSE are synchronized as well. Merge the publication pull request before tagging this repository. A successful generator release then creates the matching annotated antono2/opencl tag; rerunning the release is safe when that tag already targets the same commit. The published DISTRIBUTION_FILES manifest records every synchronized path so the publisher can detect and remove files retired from the canonical source.

The generated src/opencl.v is copied to the separately published opencl V module together with the hand-written discovery, ownership, program, event, image, SVM, capability, and external-interoperability layers under src/.

See API_DESIGN.md for the conventions shared with the companion Vulkan convenience layer.

The generated surface covers the complete cumulative OpenCL 1.0 through 3.0 core command, type, and constant API. It also includes the portable cl_khr_il_program, cl_khr_create_command_queue, cl_khr_subgroups, and cl_khr_suggested_local_work_size compatibility entry points. External-memory interop includes cl_khr_semaphore, cl_khr_external_semaphore, cl_khr_external_memory, their opaque-FD variants, Linux DMA-BUF memory, and sync-file semaphore reimport. Further extensions will be added incrementally while keeping generated output runtime-tested. cl_khr_device_uuid exposes stable device and driver identity queries for interop device matching. Optional extension commands are resolved through the ICD at runtime instead of being required linker symbols, allowing the same module to build against older OpenCL loaders when those extensions are not used. The hand-written interoperability layer validates device capabilities, resolves commands for the selected platform, imports opaque-FD buffers and binary semaphores into owned wrappers, and returns owned events from acquire, release, wait, and signal operations for explicit dependency chaining.

Typed buffers, images, SVM allocations, and argument helpers require plain C-layout element types without V-managed references. Size multiplication is checked before native allocation, external import, and transfer calls. Typed images additionally verify that sizeof(T) matches one complete pixel in the requested OpenCL image format. See OWNERSHIP.md for the copy and cleanup rules of owning value wrappers.

Test

The smoke test uses the official OpenCL headers and the system ICD loader:

git clone --depth 1 https://github.com/KhronosGroup/OpenCL-Headers.git openclheaders
OPENCL_HEADERS=$PWD/openclheaders v -cc gcc run test

The smoke test builds and executes a small kernel, so an OpenCL implementation is required. On Debian or Ubuntu, PoCL provides a suitable CPU implementation:

sudo apt install ocl-icd-opencl-dev pocl-opencl-icd

Examples

examples/vector_add demonstrates the generated module's owned convenience layer with asynchronous transfers, event dependencies, kernel dispatch, profiling, and cleanup.

examples/image_svm executes an image-to-image kernel through typed Image2D owners and an owned sampler, then runs a second kernel directly over typed shared virtual memory when the selected device advertises buffer SVM support. On macOS, Apple's OpenCL 1.2 framework does not expose SVM entry points, so the typed SVM API reports the feature as unavailable.

examples/vulkan_particles is an interactive particle-galaxy example built around OpenCL compute and Vulkan presentation. Its display-independent smoke runner exercises the particle kernel on CPU or GPU OpenCL devices; the Vulkan renderer prefers UUID-matched external-memory interop and falls back to host staging. On qualifying hardware, OpenCL updates the same exported allocation that Vulkan consumes as a vertex buffer.