Samples for loading kernel files

[MathiasMagnus]

Hi everyone!

I wanted to drive high-level discussions on how the repo should look like via actual code samples. I've taken the liberty of going forward and writing some samples which are pretty much missing from all SDK samples, because each one has chosen one given strategy from the vast array of methods on loading kernel files.

My currently private repo is here.

It explores three methods, although I do intend on adding:

• going by compiler defines only without involving symbols or files
• means of embedding kernel code into the executable

There is an orthogonal aspect, which is loading kernel code or some IR / vendor ISA and compiling it offline. Adding the necessary Clang steps to CMake shouldn't be too much.

These first samples immediately touch on an unrelated topic, of how to present utilities from the SDK to the user, however I'll create a separate issue for that.

[jrprice]

My currently private repo is here.

We can't see this repo because it's private. Can you either make it public, or perhaps open as a PR here so we can discuss and iterate? Or you could make it a secret gist and share the link.

[MathiasMagnus]

Okay, made it public. I made it private cause I didn't want to think about licensing, but there's no black magic in there.

[kpet]

I've had a better look at these samples. This is very much in the spirit of what we should have in the SDK. Kudos for the nice CMake + code + README approach, you're setting the bar :).

[jrprice]

One high-level question that comes to mind here is about which languages we want to provide examples for. These examples use C++ with the C++ bindings. Do we also want to show example code using the C API directly?

[MathiasMagnus]

@jrprice When we were only kicking off discussions about an OpenCL Primer (and the SDK is likely to take its place) I too asked how large a ground we should cover. Kévin, Ben and I seemed to be in agreement on favoring the C++ bindings, but by no means should that mean that C, or even Python as a popular language should be left out. Ultimately we can't do everything (why not OpenCL.Net?), so we should follow some order.

I'd say going C/C++ first would be a wise choice and leave other bindings up to the community and not rule them out on sight. If quality Python content would like to come into the repo, I'd say we should accept.

[MathiasMagnus]

I've added the PreprocessorDefine and Embed samples.

I believe Embed has the best feature set, with its downside being only that it may blow up binary size, which for the most part is a non-issue. (At GIMP/GEGL scale it can cause problems, but not in the SDK.)

As I've noted in the notes at the end of Embed's markdown, the OpenCL SDK should really provide utility macros/functions for CMake scripts to take the hassle out of embedding. Whether

• headers actually manifest to users or we force include them like add_sycl_to_target() does, or
• whether we separate the symbol into its own translation unit so Main.cpp need not be recompiled, only relinked if the kernels changes, or
• whether the symbol name is customizable, should there be more kernel files...
  we can discuss all that, but we should try to ship something. As outlined in Utility library #2, the SDK package OpenCL::SDK could automatically expose these utilities, as do SYCL libraries "leak" add_sycl_to_target().

Other build systems

As for being so hung up on CMake: it's what most OSS libraries tend to use. OpenCL is cross-platform, so should our 1st build system be too. If someone is versed in MSBuild and/or Meson, I believe we should be open to incorporating support for those too, and while I've been a prime time VS user for 8 years (using VS Code now), I'm not fluent enough with MSBuild schemas to add .cl language support or a meaningful Add-On that's installable from the VS Marketplace.

If anyone is super at home within CMake's codebase, actually having OpenCL C language support for .cl files would be super awesome. Adding an OPENCL_C language (along with OPENCL_CXX, as they are largely align) for which Clang is looked for would allow to simplify the part of compiling to SPIR/SPIR-V tremendously. Embedding file contents as a symbol is again orthogonal.

[bashbaug]

I've had a better look at these samples. This is very much in the spirit of what we should have in the SDK. Kudos for the nice CMake + code + README approach, you're setting the bar :).

I agree, these samples look very nice. I think the README explaining why the sample exists and what it is doing is just as important as the code itself (and takes at least as much time to write!), and I like the descriptions you've done so far.

I think it's interesting that we seem to have at least two potential "classes" of content in the SDK, and I think they're both things that different users may find interesting:

1. The content in OpenCL-KernelLoad is about engineering and automation and setting up a build system.

2. The content in SimpleOpenCLSamples is more about minimal samples demonstrating API features.

I think with this content plus some docs and utility libraries we'll have the start of a respectable SDK.

[bashbaug]

Regarding docs, I think we should follow the model of the Vulkan Guide and develop the initial docs in plain markdown until we prove we need something fancier. I think it would be nice if the docs were in the SDK also, especially since we could link to relevant samples, but I suppose it could be in its own git repo also.

I know this is a non-trivial amount of work. Maybe if one person developed an outline for an "OpenCL Guide" we could divide up sections so one person doesn't have to author the entire guide?

There are also some specific docs I think we should write. One is a "Getting Started" guide, similar to this page for OpenGL. I've also gotten pretty good mileage out of my Troubleshooting OpenCL on Linux doc, which we could port over and potentially expand to other OSes.