Add API specification to retrieve kernel binary program data

Signed-off-by: John Falkowski <[email protected]>

Author: johntfalk

scripts/core/EXT_Exp_KernelBinary.rst

@@ -0,0 +1,53 @@
+<%
+import re
+from templates import helper as th
+%><%
+    OneApi=tags['$OneApi']
+    x=tags['$x']
+    X=x.upper()
+%>
+:orphan:
+
+.. _ZE_extension_kernel_binary_exp:
+
+=========================================
+ Get Kernel Binary Program Data Extension
+=========================================
+
+API
+----
+
+* Functions
+
+    * ${x}KernelGetBinaryExp
+
+
+===============================
+ Get Kernel Binary Program Data
+===============================
+
+After a kernel is created with zeKernelCreate, the user will be able to retrieve the kernel
+binary program data, which is in GEN ISA format.  Each valid kernel handle will provide the
+information required to retrieve such data.  The user may then save this data to a file for
+disassembly and analysis.  There is a 2-step process to obtain this data.  The first step is
+to find the size of binary program data, so that memory may be allocated to store such data.
+This is done by providing an input storage pointer with nullptr value.  After allocating a
+storage array of this size, the user then provides the valid size and storage location to 
+retrieve the data.
+
+The following pseudo-code shows how to obtain the kernel binary program data save to a file:
+
+.. parsed-literal::
+
+    #include <fstream>
+    //hKernel = valid kernel handle
+    size_t kBinarySize = 0;
+    char *progArray;
+    ${x}KernelGetBinaryExp(hKernel, &KBinarysize, nullptr);
+    progArray = new char[kBinarySize];
+    ${x}KernelGetBinaryExp(hKernel, &kBinarySize, progArray);
+    const std::string filePath = "program.bin";
+    std::ofstream stream(filePath, std::ios::out | std::ios::binary);
+    stream.write(reinterpret_cast<const char *>(progArray), kBinarySize);
+    stream.close();
+    delete[] progArray;

scripts/core/kernelBinary.yml

@@ -0,0 +1,40 @@
+#
+# Copyright (C) 2024 Intel Corporation
+#
+# SPDX-License-Identifier: MIT
+#
+# See YaML.md for syntax definition
+#
+--- #--------------------------------------------------------------------------
+type: header
+desc: "Intel $OneApi Level-Zero Extension for retrieving kernel binary program data."
+version: "1.11"
+--- #--------------------------------------------------------------------------
+type: macro
+desc: "Get Kernel Binary Extension Name"
+version: "1.11"
+name: $X_GET_KERNEL_BINARY_EXP_NAME
+value: '"$X_extension_kernel_binary_exp"'
+--- #--------------------------------------------------------------------------
+type: function
+desc: "Retrieves kernel binary program data (ISA GEN format)."
+version: "1.11"
+class: $xKernel
+name: GetBinaryExp
+decl: static
+ordinal: "0"
+details:
+    - "A valid kernel handle must be created with zeKernelCreate."
+    - "Returns Intel Graphics Assembly (GEN ISA) format binary program data for kernel handle."
+    - "The application may call this function from simultaneous threads."
+    - "The implementation of this function must be thread-safe."
+params:
+    - type: "$x_kernel_handle_t"
+      name: hKernel
+      desc: "[in] Kernel handle"
+    - type: "size_t*"
+      name: pSize
+      desc: "[in, out] pointer to variable with size of GEN ISA binary"
+    - type: "char*"
+      name: pKernelBinary
+      desc: [in,out] pointer to storage area for GEN ISA binary function