add additional command buffer error checking using test queues (#127)

* add an option for command buffer emulation enhanced error checking

Adds an option for enhanced error checking, disabled by default.
Enhanced error checking creates special test queues when a command
buffer is created, and enqueues a barrier blocked by a user event
into the test queue.  Then, before a command is recorded into a
command buffer, it is also enqueued into the test queue, to identify
command errors.  When the command buffer is finalized the user event
is set to an error state, causing all of the commands in the test
queue to be terminated.

* fix typo

* add an environment variable to control enhanced error checking

* add checks for a few more command buffer errors

Author: bashbaug

include/getenv_util.hpp

@@ -0,0 +1,98 @@
+/*
+// Copyright (c) 2022-2024 Ben Ashbaugh
+//
+// SPDX-License-Identifier: MIT
+*/
+#pragma once
+
+#include <stdlib.h>
+#include <string.h>
+
+#include <string>
+
+#if defined(_WIN32)
+
+#include <windows.h>
+
+#define GETENV( _name, _value ) _dupenv_s( &_value, NULL, _name )
+#define FREEENV( _value ) free( _value )
+
+#else
+
+#define GETENV( _name, _value ) _value = getenv(_name)
+#define FREEENV( _value ) (void)_value
+
+#endif
+
+static inline bool getControlFromEnvironment(
+    const char* name,
+    void* pValue,
+    size_t size )
+{
+    char* envVal = NULL;
+    GETENV( name, envVal );
+
+    if( envVal != NULL )
+    {
+        if( size == sizeof(unsigned int) )
+        {
+            unsigned int* puVal = (unsigned int*)pValue;
+            *puVal = atoi(envVal);
+        }
+        else if( strlen(envVal) < size )
+        {
+            char* pStr = (char*)pValue;
+            strcpy( pStr, envVal );
+        }
+
+        FREEENV( envVal );
+        return true;
+    }
+
+    return false;
+}
+
+template <class T>
+static bool getControl(
+    const char* name,
+    T& value )
+{
+    unsigned int readValue = 0;
+    bool success = getControlFromEnvironment( name, &readValue, sizeof(readValue) );
+    if( success )
+    {
+        value = readValue;
+    }
+
+    return success;
+}
+
+template <>
+bool getControl<bool>(
+    const char* name,
+    bool& value )
+{
+    unsigned int readValue = 0;
+    bool success = getControlFromEnvironment( name, &readValue, sizeof(readValue) );
+    if( success )
+    {
+        value = ( readValue != 0 );
+    }
+
+    return success;
+}
+
+template <>
+bool getControl<std::string>(
+    const char* name,
+    std::string& value )
+{
+    char readValue[256] = "";
+    bool success = getControlFromEnvironment( name, readValue, sizeof(readValue) );
+    if( success )
+    {
+        value = readValue;
+    }
+
+    return success;
+}

layers/10_cmdbufemu/README.md

@@ -26,9 +26,17 @@ clGetExtensionFunctionAddressForPlatform
 clInitLayer
 ```
 
+## Optional Controls
+
+The following environment variables can modify the behavior of the command buffer emulation layer:
+
+| Environment Variable | Behavior |  Example Format |
+|----------------------|----------|-----------------|
+| `CMDBUFEMU_EnhancedErrorChecking` | Enables additional error checking when commands are added to a command buffer using a command buffer "test queue".  By default, the additional error checking is disabled. | `export CMDBUFEMU_EnhancedErrorChecking=1`<br/><br/>`set CMDBUFEMU_EnhancedErrorChecking=1` |
+
 ## Known Limitations
 
 This section describes some of the limitations of the emulated `cl_khr_command_buffer` functionality:
 
-* Many error conditions are not properly checked for and returned.
+* Some error conditions are not properly checked for and returned.
 * Many functions are not thread safe.