Driver DDI Handles Extension (#277)

* Driver DDI Handles Extension
* Have single ze_handle_t and update .rst docs
* Add flag for checking if a ddiTable is valid

Signed-off-by: Neil R. Spruit <[email protected]>

Author: nrspruit

scripts/core/EXT_Driver_DDIHandles.rst

@@ -0,0 +1,73 @@
+<%
+import re
+from templates import helper as th
+%><%
+    OneApi=tags['$OneApi']
+    x=tags['$x']
+    X=x.upper()
+%>
+:orphan:
+
+.. _ZE_extension_driver_ddi_handles:
+
+==========================================
+ Driver Direct Device Interface (DDI) Handles Extension
+==========================================
+
+API
+----
+
+* Enumerations
+    * ${x}_driver_ddi_handles_ext_version_t
+
+* Structures
+    * ${x}_driver_ddi_handle_ext_flags_t
+    * ${x}_driver_ddi_handles_ext_properties_t
+    * ze_handle_t
+    * ze_dditable_driver_t
+    * zet_dditable_driver_t
+    * zes_dditable_driver_t
+
+See `ze*_ddi.h` for definitions of `ze_dditable_driver_t`, `zet_dditable_driver_t`, `zes_dditable_driver_t`.
+`ze_handle_t` is defined in ze_ddi_common.h. To use it, include `ze_ddi_common.h`.
+
+Handle Structures:
+~~~~~~~~~~~~~~~~~
+
+    /// @brief Handle with pointer to Dispatch Container allocated by the driver at the beginning of every L0 Core handle
+    typedef struct _ze_handle_t
+    {
+        ze_dditable_driver_t *pCore; // [in] pointer to _ze_dditable_t_ object related to this handle
+        zet_dditable_driver_t *pTools; // [in] pointer to _zet_dditable_t_ object related to this handle
+        zes_dditable_driver_t *pSysman; // [in] pointer to _zes_dditable_t_ object related to this handle
+    } ze_handle_t;
+
+DDI Handles Extension:
+~~~~~~~~~~~~~~~~~~~~~
+
+Nowadays there are many possible scenarios of multiple Level Zero runtimes in the system (GPU + NPU, dGPU + iGPU on Windows, mainstream GPU + legacy GPU on Linux).
+Our current handling of multi runtime scenario in Loader has many issues:
+  - performance degradation
+  - Level Zero API handles are stored in per-type maps, accessing these maps costs, especially in hot paths
+  - putting and removing entries from map needs additional mutex to ensure thread-safety
+  - there is significant perfomance difference between runing application when there is only one runtime active and many runtimes active, even if only one is really used by application.
+    As initialization overhead is acceptable, any further API calls should not cause performance degradation. E.g. when running [`SetKernelArgSvmPointer`](https://github.com/intel/compute-benchmarks/blob/master/source/benchmarks/api_overhead_benchmark/implementations/l0/set_kernel_arg_svm_pointer_l0.cpp) test from [`api_overhead_benchmark`](https://github.com/intel/compute-benchmarks/tree/master/source/benchmarks/api_overhead_benchmark) there is degradation from 0.817us to 2.724us caused only by presence of second runtime on the system.
+  - when using driver extensions, application bypasses Level Zero loader and calls runtime functions directly
+  - handles that application got from loader is wrapped by loader's handle type and can't be passed to runtime directly, therefore translation is required;
+    translation could be applied on two sides - app side / runtime side. How to detect double translation?
+  - extension may create ze_event_t object that can be then used in core API - loader cannot recognize it
+
+The solution which solves this problem is to define a base layout of every handle type directly in L0 spec ensuring that all L0 API handles contain a header with pointers to appropriate driver ddi tables.
+Backward compatibility is covered as new loader will still support runtimes that do not support this extension.
+Loader should verify the support based on extension property queried from zeDriverGetExtensionProperties.
+
+Example Implementation of L0 Loader functions:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. parsed-literal::
+    ZE_APIEXPORT ze_result_t ZE_APICALL zeContextCreate(
+        ze_driver_handle_t hDriver,
+        const ze_context_desc_t *desc,
+        ze_context_handle_t *phContext) {
+        return hDriver->pCore->pContext->pfnCreate(hDriver, desc, phContext);
+    }

scripts/core/common.yml

@@ -587,6 +587,10 @@ etors:
       desc: $x_external_semaphore_wait_params_ext_t
       version: "1.12"
       value: "0x00020026"
+    - name: DRIVER_DDI_HANDLES_EXT_PROPERTIES
+      desc: $x_driver_ddi_handles_ext_properties_t
+      version: "1.12"
+      value: "0x00020027"
     - name: COMMAND_GRAPH_EXP_DESC
       desc: $x_command_graph_exp_desc_t
       version: "2.0"

scripts/core/driverDDIHandles.yml

@@ -0,0 +1,48 @@
+#
+# Copyright (C) 2024 Intel Corporation
+#
+# SPDX-License-Identifier: MIT
+#
+# See YaML.md for syntax definition
+#
+--- #--------------------------------------------------------------------------
+type: header
+desc: "Intel $OneApi Level-Zero Extension for Driver Direct Device Interface (DDI) Handles"
+version: "1.12"
+--- #--------------------------------------------------------------------------
+type: macro
+desc: "Driver Direct Device Interface (DDI) Handles Extension Name"
+version: "1.12"
+name: $X_DRIVER_DDI_HANDLES_EXT_NAME
+value: '"$X_extension_driver_ddi_handles"'
+--- #--------------------------------------------------------------------------
+type: enum
+desc: "Driver Direct Device Interface (DDI) Handles Extension Version(s)"
+version: "1.12"
+name: $x_driver_ddi_handles_ext_version_t
+etors:
+    - name: "1_0"
+      value: "$X_MAKE_VERSION( 1, 0 )"
+      desc: "version 1.0"
+--- #--------------------------------------------------------------------------
+type: enum
+desc: "Driver Direct Device Interface (DDI) Handle Extension Flags"
+class: $xDriver
+name: $x_driver_ddi_handle_ext_flags_t
+etors:
+    - name: DDI_HANDLE_EXT_SUPPORTED 
+      desc: "Driver Supports DDI Handles Extension"
+--- #--------------------------------------------------------------------------
+type: struct
+desc: "Driver DDI Handles properties queried using $xDriverGetProperties"
+version: "1.12"
+class: $xDriver
+name: $x_driver_ddi_handles_ext_properties_t
+base: $x_base_properties_t
+members:
+    - type: $x_driver_ddi_handle_ext_flags_t
+      name: flags
+      desc: |
+            [out] 0 (none) or a valid combination of ::ze_driver_ddi_handle_ext_flags_t
+details:
+    - "This structure may be returned from $xDriverGetProperties, via the `pNext` member of $x_driver_properties_t."

scripts/generate_code.py

@@ -68,6 +68,26 @@ def _mako_ddi_h(path, namespace, tags, version, revision, specs, meta):
         specs=specs,
         meta=meta)
 
+"""
+    generates ddi_common header
+"""
+def _mako_ddi_common_h(path, namespace, tags, version, revision, specs, meta):
+    template = "ddi_common.h.mako"
+    fin = os.path.join("templates", template)
+
+    filename = "%s_ddi_common.h"%(namespace)
+    fout = os.path.join(path, filename)
+
+    print("Generating %s..."%fout)
+    return util.makoWrite(
+        fin, fout,
+        ver=version,
+        rev=revision,
+        namespace=namespace,
+        tags=tags,
+        specs=specs,
+        meta=meta)
+
 """
     generates python files from the specification documents
 """
@@ -95,6 +115,8 @@ def _generate_api_cpp(incpath, srcpath, namespace, tags, version, revision, spec
     loc = _mako_api_h(incpath, namespace, tags, version, revision, specs, meta)
     loc += _mako_api_cpp(srcpath, namespace, tags, version, revision, specs, meta)
     loc += _mako_ddi_h(incpath, namespace, tags, version, revision, specs, meta)
+    if namespace == "ze":
+        loc += _mako_ddi_common_h(incpath, namespace, tags, version, revision, specs, meta)
 
     return loc
 

scripts/templates/ddi.h.mako

@@ -95,6 +95,15 @@ typedef struct _${n}_dditable_t
     ${th.append_ws(tbl['type'], 35)} ${tbl['name']};
 %endfor
 } ${n}_dditable_t;
+/// @brief Container for all DDI tables with version and tables set by the Driver
+typedef struct _${n}_dditable_driver_t
+{
+    ze_api_version_t    version;
+    uint8_t             isValidFlag;
+%for tbl in th.get_pfntables(specs, meta, n, tags):
+    ${th.append_ws(tbl['ptype'], 35)} ${tbl['name']};
+%endfor
+} ${n}_dditable_driver_t;
 
 #if defined(__cplusplus)
 } // extern "C"

scripts/templates/ddi_common.h.mako

@@ -0,0 +1,45 @@
+<%
+import re
+from templates import helper as th
+%><%
+    n=namespace
+    N=n.upper()
+
+    x=tags['$x']
+    X=x.upper()
+%>/*
+ *
+ * Copyright (C) 2024 Intel Corporation
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * @file ${n}_ddi_common.h
+ * @version v${ver}-r${rev}
+ *
+ */
+#ifndef _${N}_DDI_COMMON_H
+#define _${N}_DDI_COMMON_H
+#if defined(__cplusplus)
+#pragma once
+#endif
+#include "ze_ddi.h"
+#include "zet_ddi.h"
+#include "zes_ddi.h"
+
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+/// @brief Handle with pointers to Dispatch Tables allocated by the driver at the beginning of every L0 object handle.
+typedef struct _${n}_handle_t
+{
+    ze_dditable_driver_t *pCore; // [in] pointer to _ze_dditable_t_ object related to this handle
+    zet_dditable_driver_t *pTools; // [in] pointer to _zet_dditable_t_ object related to this handle
+    zes_dditable_driver_t *pSysman; // [in] pointer to _zes_dditable_t_ object related to this handle
+} ${n}_handle_t;
+
+#if defined(__cplusplus)
+} // extern "C"
+#endif
+
+#endif // _${N}_DDI_COMMON_H

scripts/templates/helper.py

@@ -922,6 +922,7 @@ def get_pfntables(specs, meta, namespace, tags):
         if len(objs) > 0:
             name = get_table_name(namespace, tags, objs[0])
             table = "%s_%s_dditable_t"%(namespace, _camel_to_snake(name))
+            pTable = "%s_%s_dditable_t *"%(namespace, _camel_to_snake(name))
 
             params = []
             params.append({
@@ -944,13 +945,15 @@ def get_pfntables(specs, meta, namespace, tags):
             tables.append({
                 'name': name, 
                 'type': table,
+                'ptype': pTable,
                 'export': export,
                 'pfn': pfn,
                 'functions': objs
             })
         if len(exp_objs) > 0:
             name = get_table_name(namespace, tags, exp_objs[0])
             table = "%s_%s_dditable_t"%(namespace, _camel_to_snake(name))
+            pTable = "%s_%s_dditable_t *"%(namespace, _camel_to_snake(name))
 
             params = []
             params.append({
@@ -973,6 +976,7 @@ def get_pfntables(specs, meta, namespace, tags):
             tables.append({
                 'name': name, 
                 'type': table,
+                'ptype': pTable,
                 'export': export,
                 'pfn': pfn,
                 'functions': exp_objs