Adding Record and Replay graph APIs (#445)

Author: jchodor

scripts/core/EXT_RecordReplayGraph.rst

@@ -0,0 +1,70 @@
+<%
+import re
+from templates import helper as th
+%><%
+    OneApi=tags['$OneApi']
+    x=tags['$x']
+    X=x.upper()
+%>
+:orphan:
+
+.. _ZE_extension_record_replay_graph:
+
+===================================
+ Record and Replay Graph Extension
+===================================
+
+API
+----
+
+* Functions
+
+
+    * ${x}GraphCreateExt
+    * ${x}CommandListBeginGraphCaptureExt
+    * ${x}CommandListBeginCaptureIntoGraphExt
+    * ${x}CommandListIsGraphCaptureEnabledExt
+    * ${x}CommandListEndGraphCaptureExt
+    * ${x}CommandListGetGraphExt
+    * ${x}GraphGetPrimaryCommandListExt
+    * ${x}GraphSetDestructionCallbackExt
+    * ${x}GraphInstantiateExt
+    * ${x}CommandListAppendGraphExt
+    * ${x}ExecutableGraphGetSourceGraphExt
+    * ${x}GraphIsEmptyExt
+    * ${x}GraphDumpContentsExt
+    * ${x}ExecutableGraphDestroyExt
+    * ${x}GraphDestroyExt
+
+
+* Enumerations
+
+
+    * ${x}_record_replay_graph_ext_version_t
+    * ${x}_record_replay_graph_ext_flags_t
+    * ${x}_record_replay_graph_ext_dump_mode_t
+
+
+* Structures
+
+
+    * ${x}_record_replay_graph_ext_properties_t
+    * ${x}_record_replay_graph_ext_dump_desc_t
+
+Record and Replay Graph
+~~~~~~~~~~~~~~~~~~~~~~~
+
+This extension allows applications to capture append operations from immediate command lists into a graph, instantiate that graph, and replay it efficiently.
+
+Applications can query support and capabilities using ${x}_record_replay_graph_ext_properties_t and ${x}_record_replay_graph_ext_flags_t. Captured graphs can be inspected with ${x}GraphDumpContentsExt, and ${x}_record_replay_graph_ext_dump_desc_t controls dump behavior.
+
+Typical Flow
+~~~~~~~~~~~~
+
+1. Create a graph with ${x}GraphCreateExt, or begin capture directly on an immediate command list with ${x}CommandListBeginGraphCaptureExt.
+2. Record append operations and optionally query capture state via ${x}CommandListIsGraphCaptureEnabledExt and ${x}CommandListGetGraphExt.
+3. End capture using ${x}CommandListEndGraphCaptureExt.
+4. Instantiate an executable graph with ${x}GraphInstantiateExt.
+5. Submit the executable graph using ${x}CommandListAppendGraphExt.
+6. Optionally dump graph contents with ${x}GraphDumpContentsExt.
+7. Destroy executable and recorded graph objects using ${x}ExecutableGraphDestroyExt and ${x}GraphDestroyExt.

scripts/core/common.yml

@@ -322,6 +322,33 @@ etors:
     - name: ERROR_ADDRESS_NOT_FOUND
       desc: "[Core] address not found within specified or current context"
       version: "1.14"
+    - name: QUERY_TRUE
+      desc: "[Core, Extension] query API returned true"
+      version: "1.17"
+    - name: QUERY_FALSE
+      desc: "[Core, Extension] query API returned false"
+      version: "1.17"
+    - name: ERROR_INVALID_GRAPH
+      desc: "[Core, Extension] graph object is invalid"
+      version: "1.17"
+    - name: ERROR_GRAPH_CAPTURE_UNSUPPORTED
+      desc: "[Core, Extension] operation is not supported during graph capture"
+      version: "1.17"
+    - name: ERROR_GRAPH_CAPTURE_INVALIDATED
+      desc: "[Core, Extension] operations failed and invalidated graph capture session"
+      version: "1.17"
+    - name: ERROR_GRAPH_CAPTURE_MERGE_ATTEMPT
+      desc: "[Core, Extension] operation failed because it would merge two graph capture sessions"
+      version: "1.17"
+    - name: ERROR_COMMAND_LIST_NOT_CAPTURING
+      desc: "[Core, Extension] command list is not in graph capture mode"
+      version: "1.17"
+    - name: ERROR_GRAPH_UNJOINED_FORKS
+      desc: "[Core, Extension] graph contains unjoined forks"
+      version: "1.17"
+    - name: ERROR_GRAPH_INTERNAL_EVENT
+      desc: "[Core, Extension] operation failed because it uses a graph-internal counter-based event outside of the graph"
+      version: "1.17"
     - name: ERROR_UNKNOWN
       value: "0x7ffffffe"
       desc: "[Core] unknown or internal error"
@@ -724,6 +751,14 @@ etors:
       desc: $x_validate_runtime_requirements_output_t
       version: "1.16"
       value: "0x00020046"
+    - name: RECORD_REPLAY_GRAPH_EXT_PROPERTIES
+      desc: $x_record_replay_graph_ext_properties_t
+      version: "1.17"
+      value: "0x00020047"
+    - name: RECORD_REPLAY_GRAPH_EXT_DUMP_DESC
+      desc: $x_record_replay_graph_ext_dump_desc_t
+      version: "1.17"
+      value: "0x00020048"
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "External memory type flags"

scripts/core/event.yml

@@ -140,6 +140,11 @@ etors:
             Indicates that event will contain timestamps converted to the host time domain
             Cannot be combined with $X_EVENT_COUNTER_BASED_FLAG_DEVICE_TIMESTAMP
             It is recommended to use this flag for most users that want to correlate timestamps from the host and device into a single timeline. For host timestamps see $xDeviceGetGlobalTimestamps.
+    - name: GRAPH_EXTERNAL
+      value: "$X_BIT(6)"
+      desc: |
+            Counter-based event is used for synchronization between recorded graph commands and commands submitted outside the graph (see $xGraphInstantiateExt in $X_RECORD_REPLAY_GRAPH_EXT_NAME for details).
+      version: "1.17"
 --- #--------------------------------------------------------------------------
 type: enum
 desc: "Supported event sync mode flags"