Merge pull request #616 from veselypeta/petr/597/fix-doxygen-rendering

[UR] Format ur_api.h to fix doxygen rendering
oneapi-src · Jun 15, 2023 · 7b96d40 · 7b96d40
2 parents 1b3c5ab + 5e4f214
commit 7b96d40
Show file tree

Hide file tree

Showing 6 changed files with 30 additions and 25 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -230,14 +230,14 @@ install(
 
 set(API_JSON_FILE ${PROJECT_BINARY_DIR}/unified_runtime.json)
 
-# Generate source from the specification
-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}
-)
-
 if(UR_FORMAT_CPP_STYLE)
+    # Generate source from the specification
+    add_custom_target(generate-code USES_TERMINAL
+        WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/scripts
+        COMMAND ${Python3_EXECUTABLE} run.py --api-json ${API_JSON_FILE} --clang-format=${CLANG_FORMAT}
+        COMMAND ${Python3_EXECUTABLE} json2src.py --api-json ${API_JSON_FILE} ${PROJECT_SOURCE_DIR}
+    )
+
     # Generate and format source from the specification
     add_custom_target(generate USES_TERMINAL
         COMMAND ${CMAKE_COMMAND} --build ${CMAKE_BINARY_DIR} --target generate-code

diff --git a/include/ur.py b/include/ur.py
@@ -561,14 +561,13 @@ class ur_device_info_v(IntEnum):
                                                     ## available for this device.
     KERNEL_SET_SPECIALIZATION_CONSTANTS = 106       ## [::ur_bool_t] support the ::urKernelSetSpecializationConstants entry
                                                     ## point
-    MEMORY_BUS_WIDTH = 107                          ## [::ur_bool_t] Return 1 if the device doesn't have a notion of a "queue
-                                                    ## index". Otherwise,
-                                                    ## return the number of queue indices that are available for this device.
+    MEMORY_BUS_WIDTH = 107                          ## [uint32_t] return the width in bits of the memory bus interface of the
+                                                    ## device.
     MAX_WORK_GROUPS_3D = 108                        ## [size_t[3]] return max 3D work groups
     ASYNC_BARRIER = 109                             ## [::ur_bool_t] return true if Async Barrier is supported
     MEM_CHANNEL_SUPPORT = 110                       ## [::ur_bool_t] return true if specifying memory channels is supported
-    HOST_PIPE_READ_WRITE_SUPPORTED = 111            ## [::ur_bool_t] Return true if the device supports enqueing commands to
-                                                    ## read and write pipes from the host.
+    HOST_PIPE_READ_WRITE_SUPPORTED = 111            ## [::ur_bool_t] Return true if the device supports enqueueing commands
+                                                    ## to read and write pipes from the host.
     MAX_REGISTERS_PER_WORK_GROUP = 112              ## [uint32_t] The maximum number of registers available per block.
     IP_VERSION = 113                                ## [uint32_t] The device IP version. The meaning of the device IP version
                                                     ## is implementation-defined, but newer devices should have a higher

diff --git a/include/ur_api.h b/include/ur_api.h
@@ -921,14 +921,13 @@ typedef enum ur_device_info_t {
                                                                   ///< available for this device.
     UR_DEVICE_INFO_KERNEL_SET_SPECIALIZATION_CONSTANTS = 106,     ///< [::ur_bool_t] support the ::urKernelSetSpecializationConstants entry
                                                                   ///< point
-    UR_DEVICE_INFO_MEMORY_BUS_WIDTH = 107,                        ///< [::ur_bool_t] Return 1 if the device doesn't have a notion of a "queue
-                                                                  ///< index". Otherwise,
-                                                                  ///< return the number of queue indices that are available for this device.
+    UR_DEVICE_INFO_MEMORY_BUS_WIDTH = 107,                        ///< [uint32_t] return the width in bits of the memory bus interface of the
+                                                                  ///< device.
     UR_DEVICE_INFO_MAX_WORK_GROUPS_3D = 108,                      ///< [size_t[3]] return max 3D work groups
     UR_DEVICE_INFO_ASYNC_BARRIER = 109,                           ///< [::ur_bool_t] return true if Async Barrier is supported
     UR_DEVICE_INFO_MEM_CHANNEL_SUPPORT = 110,                     ///< [::ur_bool_t] return true if specifying memory channels is supported
-    UR_DEVICE_INFO_HOST_PIPE_READ_WRITE_SUPPORTED = 111,          ///< [::ur_bool_t] Return true if the device supports enqueing commands to
-                                                                  ///< read and write pipes from the host.
+    UR_DEVICE_INFO_HOST_PIPE_READ_WRITE_SUPPORTED = 111,          ///< [::ur_bool_t] Return true if the device supports enqueueing commands
+                                                                  ///< to read and write pipes from the host.
     UR_DEVICE_INFO_MAX_REGISTERS_PER_WORK_GROUP = 112,            ///< [uint32_t] The maximum number of registers available per block.
     UR_DEVICE_INFO_IP_VERSION = 113,                              ///< [uint32_t] The device IP version. The meaning of the device IP version
                                                                   ///< is implementation-defined, but newer devices should have a higher

diff --git a/scripts/core/device.yml b/scripts/core/device.yml
@@ -370,17 +370,15 @@ etors:
     - name: KERNEL_SET_SPECIALIZATION_CONSTANTS
       desc: "[$x_bool_t] support the $xKernelSetSpecializationConstants entry point"
     - name: MEMORY_BUS_WIDTH
-      desc: |
-            [$x_bool_t] Return 1 if the device doesn't have a notion of a "queue index". Otherwise,
-            return the number of queue indices that are available for this device.
+      desc: "[uint32_t] return the width in bits of the memory bus interface of the device."
     - name: MAX_WORK_GROUPS_3D
       desc: "[size_t[3]] return max 3D work groups"
     - name: ASYNC_BARRIER
       desc: "[$x_bool_t] return true if Async Barrier is supported"
     - name: MEM_CHANNEL_SUPPORT
       desc: "[$x_bool_t] return true if specifying memory channels is supported"
     - name: HOST_PIPE_READ_WRITE_SUPPORTED
-      desc: "[$x_bool_t] Return true if the device supports enqueing commands to read and write pipes from the host."
+      desc: "[$x_bool_t] Return true if the device supports enqueueing commands to read and write pipes from the host."
     - name: MAX_REGISTERS_PER_WORK_GROUP
       desc: "[uint32_t] The maximum number of registers available per block."
     - name: IP_VERSION

diff --git a/scripts/run.py b/scripts/run.py
@@ -119,6 +119,7 @@ def main():
     parser.add_argument("--ver", type=str, default=get_version_from_cmakelists(),
                         required=False, help="specification version to generate.")
     parser.add_argument("--api-json", type=str, default="unified_runtime.json", required=False, help="json output file for the spec")
+    parser.add_argument("--clang-format", type=str, default="clang-format", required=False, help="path to clang-format executable")
     args = vars(parser.parse_args())
     args['rev'] = revision()
 
@@ -166,6 +167,13 @@ def main():
 
                 generate_code.generate_api(incpath, srcpath, config['namespace'], config['tags'], args['ver'], args['rev'], specs, input['meta'])
 
+                # clang-format ur_api.h
+                proc = subprocess.run([args['clang_format'], "--style=file", "-i" , "ur_api.h"], stderr=subprocess.PIPE, cwd=incpath)
+                if proc.returncode != 0:
+                    print("-- clang-format failed with non-zero return code. --")
+                    print(proc.stderr.decode())
+                    raise Exception("Failed to format ur_api.h")
+
                 if args['rst']:
                     generate_docs.generate_rst(docpath, config['name'], config['namespace'], config['tags'], args['ver'], args['rev'], specs, input['meta'])
 
@@ -198,8 +206,9 @@ def main():
 
         print("\nCompleted in %.1f seconds!"%(time.time() - start))
 
-    except:
+    except BaseException as e:
         print("Failed to generate specification.")
+        print(e)
         return sys.exit(1)
 
 

diff --git a/source/common/ur_params.hpp b/source/common/ur_params.hpp
@@ -3306,10 +3306,10 @@ inline void serializeTagged(std::ostream &os, const void *ptr,
     } break;
 
     case UR_DEVICE_INFO_MEMORY_BUS_WIDTH: {
-        const ur_bool_t *tptr = (const ur_bool_t *)ptr;
-        if (sizeof(ur_bool_t) > size) {
+        const uint32_t *tptr = (const uint32_t *)ptr;
+        if (sizeof(uint32_t) > size) {
             os << "invalid size (is: " << size
-               << ", expected: >=" << sizeof(ur_bool_t) << ")";
+               << ", expected: >=" << sizeof(uint32_t) << ")";
             return;
         }
         os << (void *)(tptr) << " (";