Add ur_program_properties_t for program creation

CMakeLists.txt

@@ -176,14 +176,14 @@ install(
 set(API_JSON_FILE ${PROJECT_BINARY_DIR}/unified_runtime.json)
 
 # Generate source from the specification
-add_custom_target(generate-code
+add_custom_target(generate-code USES_TERMINAL
     WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/scripts
     COMMAND ${Python3_EXECUTABLE} run.py --api-json ${API_JSON_FILE}
     COMMAND ${Python3_EXECUTABLE} json2src.py --api-json ${API_JSON_FILE} ${PROJECT_SOURCE_DIR}
 )
 
 # Generate and format source from the specification
-add_custom_target(generate
+add_custom_target(generate USES_TERMINAL
     COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --target generate-code
     COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --target cppformat
 )

include/ur.py

@@ -205,6 +205,7 @@ def __str__(self):
 ## @brief Defines structure types
 class ur_structure_type_v(IntEnum):
     IMAGE_DESC = 0                                  ## ::ur_image_desc_t
+    PROGRAM_PROPERTIES = 1                          ## ::ur_program_properties_t
 
 class ur_structure_type_t(c_int):
     def __str__(self):
@@ -1034,6 +1035,55 @@ def __str__(self):
         return str(ur_api_version_v(self.value))
 
 
+###############################################################################
+## @brief Program metadata property type.
+class ur_program_metadata_type_v(IntEnum):
+    UINT32 = 0                                      ## type is a 32-bit integer.
+    UINT64 = 1                                      ## type is a 64-bit integer.
+    BYTE_ARRAY = 2                                  ## type is a byte array.
+    STRING = 3                                      ## type is a null-terminated string.
+
+class ur_program_metadata_type_t(c_int):
+    def __str__(self):
+        return str(ur_program_metadata_type_v(self.value))
+
+
+###############################################################################
+## @brief Program metadata value union.
+class ur_program_metadata_value_t(Structure):
+    _fields_ = [
+        ("data32", c_ulong),                                            ## [in] inline storage for the 32-bit data, type
+                                                                        ## ::UR_PROGRAM_METADATA_TYPE_UINT32.
+        ("data64", c_ulonglong),                                        ## [in] inline storage for the 64-bit data, type
+                                                                        ## ::UR_PROGRAM_METADATA_TYPE_UINT64.
+        ("pString", c_char_p),                                          ## [in] pointer to null-terminated string data, type
+                                                                        ## ::UR_PROGRAM_METADATA_TYPE_STRING.
+        ("pData", c_void_p)                                             ## [in] pointer to binary data, type
+                                                                        ## ::UR_PROGRAM_METADATA_TYPE_BYTE_ARRAY.
+    ]
+
+###############################################################################
+## @brief Program metadata property.
+class ur_program_metadata_t(Structure):
+    _fields_ = [
+        ("pName", c_char_p),                                            ## [in] null-terminated metadata name.
+        ("type", ur_program_metadata_type_t),                           ## [in] the type of metadata value.
+        ("size", c_size_t),                                             ## [in] size in bytes of the data pointed to by value.pData, or 0 when
+                                                                        ## value size is less than 64-bits and is stored directly in value.data.
+        ("value", ur_program_metadata_value_t)                          ## [in] the metadata value storage.
+    ]
+
+###############################################################################
+## @brief Program creation properties.
+class ur_program_properties_t(Structure):
+    _fields_ = [
+        ("stype", ur_structure_type_t),                                 ## [in] type of this structure
+        ("pNext", c_void_p),                                            ## [in,out][optional] pointer to extension-specific structure
+        ("count", c_ulong),                                             ## [in] the number of entries in pMetadatas, if count is greater than
+                                                                        ## zero then pMetadatas must not be null.
+        ("pMetadatas", POINTER(ur_program_metadata_t))                  ## [in][optional][range(0,count)] pointer to array of metadata entries.
+    ]
+
 ###############################################################################
 ## @brief Get Program object information
 class ur_program_info_v(IntEnum):
@@ -1291,16 +1341,16 @@ class ur_event_dditable_t(Structure):
 ###############################################################################
 ## @brief Function-pointer for urProgramCreate
 if __use_win_types:
-    _urProgramCreate_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, c_ulong, POINTER(ur_module_handle_t), c_char_p, POINTER(ur_program_handle_t) )
+    _urProgramCreate_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, c_ulong, POINTER(ur_module_handle_t), c_char_p, POINTER(ur_program_properties_t), POINTER(ur_program_handle_t) )
 else:
-    _urProgramCreate_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, c_ulong, POINTER(ur_module_handle_t), c_char_p, POINTER(ur_program_handle_t) )
+    _urProgramCreate_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, c_ulong, POINTER(ur_module_handle_t), c_char_p, POINTER(ur_program_properties_t), POINTER(ur_program_handle_t) )
 
 ###############################################################################
 ## @brief Function-pointer for urProgramCreateWithBinary
 if __use_win_types:
-    _urProgramCreateWithBinary_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, ur_device_handle_t, c_size_t, POINTER(c_ubyte), POINTER(ur_program_handle_t) )
+    _urProgramCreateWithBinary_t = WINFUNCTYPE( ur_result_t, ur_context_handle_t, ur_device_handle_t, c_size_t, POINTER(c_ubyte), POINTER(ur_program_properties_t), POINTER(ur_program_handle_t) )
 else:
-    _urProgramCreateWithBinary_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, ur_device_handle_t, c_size_t, POINTER(c_ubyte), POINTER(ur_program_handle_t) )
+    _urProgramCreateWithBinary_t = CFUNCTYPE( ur_result_t, ur_context_handle_t, ur_device_handle_t, c_size_t, POINTER(c_ubyte), POINTER(ur_program_properties_t), POINTER(ur_program_handle_t) )
 
 ###############################################################################
 ## @brief Function-pointer for urProgramRetain

include/ur_api.h

@@ -227,7 +227,8 @@ typedef enum ur_result_t {
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Defines structure types
 typedef enum ur_structure_type_t {
-    UR_STRUCTURE_TYPE_IMAGE_DESC = 0, ///< ::ur_image_desc_t
+    UR_STRUCTURE_TYPE_IMAGE_DESC = 0,         ///< ::ur_image_desc_t
+    UR_STRUCTURE_TYPE_PROGRAM_PROPERTIES = 1, ///< ::ur_program_properties_t
     /// @cond
     UR_STRUCTURE_TYPE_FORCE_UINT32 = 0x7fffffff
     /// @endcond
@@ -4287,6 +4288,55 @@ urGetLastResult(
 #if !defined(__GNUC__)
 #pragma region program
 #endif
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Program metadata property type.
+typedef enum ur_program_metadata_type_t {
+    UR_PROGRAM_METADATA_TYPE_UINT32 = 0,     ///< type is a 32-bit integer.
+    UR_PROGRAM_METADATA_TYPE_UINT64 = 1,     ///< type is a 64-bit integer.
+    UR_PROGRAM_METADATA_TYPE_BYTE_ARRAY = 2, ///< type is a byte array.
+    UR_PROGRAM_METADATA_TYPE_STRING = 3,     ///< type is a null-terminated string.
+    /// @cond
+    UR_PROGRAM_METADATA_TYPE_FORCE_UINT32 = 0x7fffffff
+    /// @endcond
+
+} ur_program_metadata_type_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Program metadata value union.
+typedef union ur_program_metadata_value_t {
+    uint32_t data32; ///< [in] inline storage for the 32-bit data, type
+                     ///< ::UR_PROGRAM_METADATA_TYPE_UINT32.
+    uint64_t data64; ///< [in] inline storage for the 64-bit data, type
+                     ///< ::UR_PROGRAM_METADATA_TYPE_UINT64.
+    char *pString;   ///< [in] pointer to null-terminated string data, type
+                     ///< ::UR_PROGRAM_METADATA_TYPE_STRING.
+    void *pData;     ///< [in] pointer to binary data, type
+                     ///< ::UR_PROGRAM_METADATA_TYPE_BYTE_ARRAY.
+
+} ur_program_metadata_value_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Program metadata property.
+typedef struct ur_program_metadata_t {
+    char *pName;                       ///< [in] null-terminated metadata name.
+    ur_program_metadata_type_t type;   ///< [in] the type of metadata value.
+    size_t size;                       ///< [in] size in bytes of the data pointed to by value.pData, or 0 when
+                                       ///< value size is less than 64-bits and is stored directly in value.data.
+    ur_program_metadata_value_t value; ///< [in] the metadata value storage.
+
+} ur_program_metadata_t;
+
+///////////////////////////////////////////////////////////////////////////////
+/// @brief Program creation properties.
+typedef struct ur_program_properties_t {
+    ur_structure_type_t stype;               ///< [in] type of this structure
+    void *pNext;                             ///< [in,out][optional] pointer to extension-specific structure
+    uint32_t count;                          ///< [in] the number of entries in pMetadatas, if count is greater than
+                                             ///< zero then pMetadatas must not be null.
+    const ur_program_metadata_t *pMetadatas; ///< [in][optional][range(0,count)] pointer to array of metadata entries.
+
+} ur_program_properties_t;
+
 ///////////////////////////////////////////////////////////////////////////////
 /// @brief Create Program from input SPIR-V modules.
 ///
@@ -4306,17 +4356,21 @@ urGetLastResult(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == phModules`
 ///         + `NULL == phProgram`
+///         + `NULL != pProperties && pProperties->count > 0 && NULL == pProperties->pMetadatas`
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         + `NULL != pProperties && NULL != pProperties->pMetadatas && pProperties->count == 0`
 UR_APIEXPORT ur_result_t UR_APICALL
 urProgramCreate(
-    ur_context_handle_t hContext,        ///< [in] handle of the context instance
-    uint32_t count,                      ///< [in] number of module handles in module list.
-    const ur_module_handle_t *phModules, ///< [in][range(0, count)] pointer to array of modules.
-    const char *pOptions,                ///< [in][optional] pointer to linker options null-terminated string.
-    ur_program_handle_t *phProgram       ///< [out] pointer to handle of program object created.
+    ur_context_handle_t hContext,               ///< [in] handle of the context instance
+    uint32_t count,                             ///< [in] number of module handles in module list.
+    const ur_module_handle_t *phModules,        ///< [in][range(0, count)] pointer to array of modules.
+    const char *pOptions,                       ///< [in][optional] pointer to linker options null-terminated string.
+    const ur_program_properties_t *pProperties, ///< [in][optional] pointer to program creation properties.
+    ur_program_handle_t *phProgram              ///< [out] pointer to handle of program object created.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Create program object from native binary.
+/// @brief Create a program object from device native binary.
 ///
 /// @details
 ///     - The application may call this function from simultaneous threads.
@@ -4335,13 +4389,17 @@ urProgramCreate(
 ///     - ::UR_RESULT_ERROR_INVALID_NULL_POINTER
 ///         + `NULL == pBinary`
 ///         + `NULL == phProgram`
+///         + `NULL != pProperties && pProperties->count > 0 && NULL == pProperties->pMetadatas`
+///     - ::UR_RESULT_ERROR_INVALID_SIZE
+///         + `NULL != pProperties && NULL != pProperties->pMetadatas && pProperties->count == 0`
 UR_APIEXPORT ur_result_t UR_APICALL
 urProgramCreateWithBinary(
-    ur_context_handle_t hContext,  ///< [in] handle of the context instance
-    ur_device_handle_t hDevice,    ///< [in] handle to device associated with binary.
-    size_t size,                   ///< [in] size in bytes.
-    const uint8_t *pBinary,        ///< [in] pointer to binary.
-    ur_program_handle_t *phProgram ///< [out] pointer to handle of Program object created.
+    ur_context_handle_t hContext,               ///< [in] handle of the context instance
+    ur_device_handle_t hDevice,                 ///< [in] handle to device associated with binary.
+    size_t size,                                ///< [in] size in bytes.
+    const uint8_t *pBinary,                     ///< [in] pointer to binary.
+    const ur_program_properties_t *pProperties, ///< [in][optional] pointer to program creation properties.
+    ur_program_handle_t *phProgram              ///< [out] pointer to handle of Program object created.
 );
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -5149,6 +5207,7 @@ typedef struct ur_program_create_params_t {
     uint32_t *pcount;
     const ur_module_handle_t **pphModules;
     const char **ppOptions;
+    const ur_program_properties_t **ppProperties;
     ur_program_handle_t **pphProgram;
 } ur_program_create_params_t;
 
@@ -5173,6 +5232,7 @@ typedef struct ur_program_create_with_binary_params_t {
     ur_device_handle_t *phDevice;
     size_t *psize;
     const uint8_t **ppBinary;
+    const ur_program_properties_t **ppProperties;
     ur_program_handle_t **pphProgram;
 } ur_program_create_with_binary_params_t;
 

include/ur_ddi.h

@@ -258,6 +258,7 @@ typedef ur_result_t(UR_APICALL *ur_pfnProgramCreate_t)(
     uint32_t,
     const ur_module_handle_t *,
     const char *,
+    const ur_program_properties_t *,
     ur_program_handle_t *);
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -267,6 +268,7 @@ typedef ur_result_t(UR_APICALL *ur_pfnProgramCreateWithBinary_t)(
     ur_device_handle_t,
     size_t,
     const uint8_t *,
+    const ur_program_properties_t *,
     ur_program_handle_t *);
 
 ///////////////////////////////////////////////////////////////////////////////

scripts/Doxyfile

@@ -740,7 +740,7 @@ CITE_BIB_FILES         =
 # messages are off.
 # The default value is: NO.
 
-QUIET                  = NO
+QUIET                  = YES
 
 # The WARNINGS tag can be used to turn on/off the warning messages that are
 # generated to standard error (stderr) by doxygen. If WARNINGS is set to YES

scripts/YaML.md

@@ -614,7 +614,7 @@ class ur_name_t(Structure):
     + `version` will be used to define the minimum API version in which the param will appear; `default="1.0"` This will also affect the order in which the param appears within the function.
   - if `class` is specified and the function is not `decl: static`, then the first param **must** be the handle associated with the class
 * A function may take the following optional sequence of scalars: {`analogue`}
-  - 'analogue` will be used as the function's remarks comment
+  - `analogue` will be used as the function's remarks comment
 * A function may take the following optional sequence of scalars or scalars to sequences: {`details`, `returns`}
   - `detail` will be used as the function's detailed comment
   - `return` will be used as the function's returns comment

scripts/core/PROG.rst

@@ -188,7 +188,7 @@ are a collection of modules that are linked together.
 
     // Create program from module
     ${x}_program_handle_t hProgram;
-    ${x}ProgramCreate(hContext, 1, &hModule, nullptr, hProgram);
+    ${x}ProgramCreate(hContext, 1, &hModule, nullptr, nullptr, hProgram);
 
 
 Kernels

scripts/core/common.yml

@@ -271,6 +271,8 @@ name: $x_structure_type_t
 etors:
     - name: IMAGE_DESC
       desc: $x_image_desc_t
+    - name: PROGRAM_PROPERTIES
+      desc: $x_program_properties_t
 --- #--------------------------------------------------------------------------
 type: struct
 desc: "Base for all properties types"