CLCREATEKERNEL(3clc)

✨ CLCREATEKERNEL ✨

okay so bestie, we're in the OpenCL manual (yes, 3clc, the whole OpenCL girlie collection) and today's episode is all about clCreateKernel — the function that ✨makes a kernel object✨. it's giving birth but for GPU functions. let's GO 💅

---

🌸 NAME 🌸

clCreateKernel — creates a kernel object. that's it, that's the whole job. iconic behavior honestly 👑

---

🦋 SYNOPSIS 🦋

cl_kernel clCreateKernel(cl_program program, const char *kernel_name,
                         cl_int *errcode_ret);

---

💖 PARAMETERS 💖

• program — a program object that has a successfully built executable. no half-baked programs allowed, she has to be ready. if it's not built, that's a whole different error, see below.
• kernel_name — a function name in the program that was declared with the __kernel qualifier. so like, the function has to actually be marked as a kernel, mkay?
• errcode_ret — this one returns an appropriate error code back to you. and if errcode_ret is NULL, then no error code is returned at all. so if you pass NULL, don't come crying about not knowing what went wrong 😭

---

💜 NOTES 💜

so like, a kernel is a function declared in a program. a kernel gets identified by the functionQualifiers(3clc) qualifier being applied to any function in a program. that's the little mark that says "yes queen, you're a kernel."

and a kernel object? it encapsulates the specific __kernel function declared in a program plus the argument values that'll be used when you actually execute that __kernel function. it's the function and its lil set of args, all bundled up together like a little care package 🎀

---

🔥 ERRORS 🔥

clCreateKernel returns a valid non-zero kernel object and sets errcode_ret to CL_SUCCESS when the kernel object is created successfully. slay!

otherwise — and hear me out — it returns a NULL value, and one of these error values comes back in errcode_ret:

• CL_INVALID_PROGRAM — if program is not a valid program object. like, that's not a program bestie, idk what that is.
• CL_INVALID_PROGRAM_EXECUTABLE — if there is no successfully built executable for program. she's not built yet, she's still in her development era.
• CL_INVALID_KERNEL_NAME — if kernel_name is not found in program. wrong name, wrong program, no kernel for you 🙈
• CL_INVALID_KERNEL_DEFINITION — if the function definition for the __kernel function given by kernel_name — like the number of arguments, the argument types — is not the same for all devices for which the program executable has been built. so if your devices can't agree on what this kernel even looks like, that's a no. it's giving miscommunication 💀
• CL_INVALID_VALUE — if kernel_name is NULL. you have to give her a name, bestie.
• CL_OUT_OF_RESOURCES — if there is a failure to allocate resources required by the OpenCL implementation on the device.
• CL_OUT_OF_HOST_MEMORY — if there is a failure to allocate resources required by the OpenCL implementation on the host.

note the difference between those last two!! one is the device being out of resources, the other is the host running out of memory. they are NOT the same vibe check, keep them straight 🫶

---

⭐ SPECIFICATION ⭐

OpenCL Specification[1]

---

🌈 SEE ALSO 🌈

clCreateKernelsInProgram(3clc), clRetainKernel(3clc), clReleaseKernel(3clc), clSetKernelArg(3clc), clGetKernelInfo(3clc), clGetKernelWorkGroupInfo(3clc), classDiagram(3clc)

---

👑 AUTHORS 👑

The Khronos Group

---

🎀 COPYRIGHT 🎀

Copyright © 2007-2011 The Khronos Group Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or associated documentation files (the "Materials"), to deal in the Materials without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to the condition that this copyright notice and permission notice shall be included in all copies or substantial portions of the Materials.

---

💅 NOTES 💅

1. OpenCL Specification page 157, section 5.7.1 - Creating Kernel Objects

---

okay that's the whole page, no cap 🧚 and fr fr, if you made it this far you're a real one. this whole thing came from The Khronos Group, dated 01/14/2021, living under the CLCREATEKERNEL(3clc) name in the OpenCL Manual. go build a kernel bestie, you got this 💖✨🦋