Merge branch 'main' into mem_obj_proposal

Author: KseniyaTikhomirova

README.md

@@ -2,6 +2,12 @@
 
 [![GHA build status](https://github.com/oneapi-src/unified-runtime/actions/workflows/cmake.yml/badge.svg?branch=main)](https://github.com/oneapi-src/unified-runtime/actions)
 
+> **Note**
+>
+> For those who intend to make a contribution to the project please read our
+> [Contribution Guide](https://oneapi-src.github.io/unified-runtime/core/CONTRIB.html)
+> for more information.
+
 ## Contents
 
 This repo contains the following:

scripts/core/CONTRIB.rst

@@ -60,6 +60,13 @@ following command (or suitable build system equivalent):
 .. _YAML syntax:
    https://github.com/oneapi-src/unified-runtime/blob/main/scripts/YaML.md
 
+.. note::
+
+    The generated source and header files are placed into ``/source`` and 
+    ``/include`` directories respectively. You *should* make no attempt to 
+    modify them directly. When the generator is run all your changes will be 
+    overwritten.
+
 Writing YAML
 ============
 
@@ -170,6 +177,15 @@ Conformance tests *must* not make assumptions about the adapter under test.
 Tests fixtures or cases *must* query for support of optional features and skip
 testing if unsupported by the adapter.
 
+All tests in the Unified Runtime project are configured to use CTest to run. 
+All conformance tests have the ``conformance`` label attached to them which 
+allows them to be run independently. To run all the conformance tests, execute 
+the following command from the build directory.
+
+.. code-block:: console
+     
+    ctest -L "conformance"
+
 Experimental Features
 =====================
 

scripts/generate_docs.py

@@ -75,6 +75,7 @@ def _make_ref(symbol, symbol_type, meta):
             ref = ":ref:`" + ref + " <" + target.replace("_", "-") + ">`"
         else:
             print("%s(%s) : error : enum symbol not found for etor %s"%(fin, iline+1, symbol))
+            raise Exception()
     elif not re.match("function", symbol_type):
         ref = ":ref:`" + ref.replace("_", "-") + "`"
     else:
@@ -92,6 +93,8 @@ def _generate_valid_rst(fin, fout, namespace, tags, ver, rev, meta):
 
     print("Generating %s..."%fout)
 
+    error = False
+
     outlines = []
     for iline, line in enumerate(util.textRead(fin)):
 
@@ -116,6 +119,7 @@ def _generate_valid_rst(fin, fout, namespace, tags, ver, rev, meta):
 
         if re.match(RE_INVALID_TAG_FORMAT, line):
             print("%s(%s) : error : invalid %s tag used"%(fin, iline+1, re.sub(RE_INVALID_TAG_FORMAT, r"\1", line)))
+            error = True
 
         newline = line # new line will contain proper tags for reStructuredText if needed.
         if re.match(RE_PROPER_TAG_FORMAT, line):
@@ -128,6 +132,7 @@ def _generate_valid_rst(fin, fout, namespace, tags, ver, rev, meta):
                     symbol_type = _find_symbol_type(symbol, meta)
                     if not symbol_type:
                         print("%s(%s) : error : symbol '%s' not found"%(fin, iline+1, symbol))
+                        error = True
                         continue
 
                     if code_block and 'function' == symbol_type:
@@ -136,6 +141,7 @@ def _generate_valid_rst(fin, fout, namespace, tags, ver, rev, meta):
                         if len(words) != len(meta['function'][symbol]['params']):
                             print("%s(%s) : error : %s parameter count mismatch - %s actual vs. %s expected"%(fin, iline+1, symbol, len(words), len(meta['function'][symbol]['params'])))
                             print("line = %s"%line)
+                            error = True
 
                     ref = _make_ref(symbol, symbol_type, meta)
                     if ref:
@@ -157,6 +163,9 @@ def _generate_valid_rst(fin, fout, namespace, tags, ver, rev, meta):
 
         outlines.append(newline)
 
+    if error:
+        raise Exception('Error during reStructuredText generation.')
+
     util.writelines(os.path.abspath(fout), outlines)
 
     return util.makoWrite(os.path.abspath(fout), fout,

scripts/parse_specs.py

@@ -430,7 +430,7 @@ def __validate_params(d, tags):
         print("%s(%s): %s!"%(os.path.abspath(f), line_num, msg))
         print("-- Function Info --")
         print(d)
-        return False
+        raise
 
 """
     filters object by version

scripts/run.py

@@ -133,69 +133,76 @@ def main():
         'meta'   : {},
         'ref'    : {}
         }
+    
+    try:
 
-    for section in configParser.sections():
-        input['configs'].append({
-            'name'     : section,
-            'namespace': configParser.get(section,'namespace'),
-            'tags'     : {'$'+key : configParser.get(section,key) for key in configParser.get(section,'tags').split(",")},
-            })
+        for section in configParser.sections():
+            input['configs'].append({
+                'name'     : section,
+                'namespace': configParser.get(section,'namespace'),
+                'tags'     : {'$'+key : configParser.get(section,key) for key in configParser.get(section,'tags').split(",")},
+                })
+
+        # phase 2: parse specs
+        for config in input['configs']:
+            specs, input['meta'], input['ref'] = parse_specs.parse(config['name'], args['ver'], config['tags'], input['meta'], input['ref'])
+            input['specs'].append(specs)
+
+        util.jsonWrite(args['api_json'], input)
 
-    # phase 2: parse specs
-    for config in input['configs']:
-        specs, input['meta'], input['ref'] = parse_specs.parse(config['name'], args['ver'], config['tags'], input['meta'], input['ref'])
-        input['specs'].append(specs)
+        # phase 3: generate files
+        if args['clean']:
+            clean()
 
-    util.jsonWrite(args['api_json'], input)
+        incpath = os.path.join("../include/")
+        srcpath = os.path.join("../source/")
+        docpath = os.path.join("../docs/")
 
-    # phase 3: generate files
-    if args['clean']:
-        clean()
+        generate_docs.prepare(docpath, args['rst'], args['html'], args['ver'])
+        generate_docs.generate_ref(docpath, input['ref'])
 
-    incpath = os.path.join("../include/")
-    srcpath = os.path.join("../source/")
-    docpath = os.path.join("../docs/")
+        for idx, specs in enumerate(input['specs']):
+            config = input['configs'][idx]
+            if args[config['name']]:
 
-    generate_docs.prepare(docpath, args['rst'], args['html'], args['ver'])
-    generate_docs.generate_ref(docpath, input['ref'])
+                generate_code.generate_api(incpath, srcpath, config['namespace'], config['tags'], args['ver'], args['rev'], specs, input['meta'])
 
-    for idx, specs in enumerate(input['specs']):
-        config = input['configs'][idx]
-        if args[config['name']]:
+                if args['rst']:
+                    generate_docs.generate_rst(docpath, config['name'], config['namespace'], config['tags'], args['ver'], args['rev'], specs, input['meta'])
 
-            generate_code.generate_api(incpath, srcpath, config['namespace'], config['tags'], args['ver'], args['rev'], specs, input['meta'])
+            if util.makeErrorCount():
+                print("\n%s Errors found during generation, stopping execution!"%util.makeErrorCount())
+                return
 
-            if args['rst']:
-                generate_docs.generate_rst(docpath, config['name'], config['namespace'], config['tags'], args['ver'], args['rev'], specs, input['meta'])
+        if args['debug']:
+            util.makoFileListWrite("generated.json")
 
-        if util.makeErrorCount():
-            print("\n%s Errors found during generation, stopping execution!"%util.makeErrorCount())
-            return
+        # phase 4: build code
+        if args['build']:
+            if not build():
+                print("\nBuild failed, stopping execution!")
+                return
 
-    if args['debug']:
-        util.makoFileListWrite("generated.json")
+        # phase 5: prep for publication of html or pdf
+        if args['html'] or args['pdf']:
+            generate_docs.generate_common(docpath, configParser.sections(), args['ver'], args['rev'])
 
-    # phase 4: build code
-    if args['build']:
-        if not build():
-            print("\nBuild failed, stopping execution!")
-            return
+        # phase 5: publish documentation
+        if args['html']:
+            generate_docs.generate_html(docpath)
 
-    # phase 5: prep for publication of html or pdf
-    if args['html'] or args['pdf']:
-        generate_docs.generate_common(docpath, configParser.sections(), args['ver'], args['rev'])
+        if args['pdf']:
+            generate_docs.generate_pdf(docpath)
 
-    # phase 5: publish documentation
-    if args['html']:
-        generate_docs.generate_html(docpath)
+        if args['update_spec']:
+            update_spec(args['update_spec'])
 
-    if args['pdf']:
-        generate_docs.generate_pdf(docpath)
+        print("\nCompleted in %.1f seconds!"%(time.time() - start))
 
-    if args['update_spec']:
-        update_spec(args['update_spec'])
+    except:
+        print("Failed to generate specification.")
+        return sys.exit(1)
 
-    print("\nCompleted in %.1f seconds!"%(time.time() - start))
 
 if __name__ == '__main__':
     main()

scripts/util.py

@@ -168,7 +168,7 @@ def makoWrite(inpath, outpath, **args):
         line = "%s: %s" % (str(traceback.error.__class__.__name__), traceback.error)
         makoErrorList.append(line)
         print(line)
-        return 0
+        raise
 
 def makoFileListWrite(outpath):
     jsonWrite(outpath, makoFileList)