Add documentation

[deliverable/exatracer.git] / scripts / gen-hip-wrappers

diff --git a/scripts/gen-hip-wrappers b/scripts/gen-hip-wrappers
index a43fd2951171f77a311528ebc42b16c4b3266df3..3a0d80b22f8e202075c484294076d0e890112e5d 100755 (executable)
--- a/scripts/gen-hip-wrappers
+++ b/scripts/gen-hip-wrappers
@@ -4,7 +4,7 @@
 #
 # Author: Olivier Dion <odion@efficios.com>
 #
-# Auto-generate lttng-ust tracepoints for HIP.
+# Auto-generate lttng-ust wrappers for HIP.
 #
 # Require: python-clang (libclang)
 
@@ -17,6 +17,7 @@ from string import Template
 import clang.cindex
 
 def list_function_declarations(root):
+    """Return all function declarations under ROOT."""
     return [
         child
         for child in root.get_children()
@@ -24,7 +25,7 @@ def list_function_declarations(root):
     ]
 
 def get_system_include_paths():
-
+    """Get default system include paths from Clang."""
     clang_args = ["clang", "-v", "-c", "-xc", "-o", "/dev/null", "/dev/null"]
     paths = []
 
@@ -42,7 +43,14 @@ def get_system_include_paths():
     return paths
 
 def parse_header(header_file, includes, defines):
-
+    """
+    Parse HEADER_FILE with Clang with INCLUDES (-I) and DEFINES (-D).
+    Return a cursor to root.
+    """
+
+    # For some reason, python-clang does not use all system include paths.
+    # Thus, compiler dependant headers, like stddef.h can not be found without
+    # this.
     args = get_system_include_paths()
 
     if includes:
@@ -63,6 +71,7 @@ def parse_header(header_file, includes, defines):
     return tu.cursor
 
 def list_functions(root):
+    """Return the list of function declarations with `hip' prefix from ROOT."""
     return [
         fn
         for fn in list_function_declarations(root)
@@ -70,7 +79,7 @@ def list_functions(root):
     ]
 
 def exact_definition(arg):
-
+    """Given a cursor ARG that is a function argument, return its exact definition."""
     ct = arg.type.get_canonical()
     if ct.kind == clang.cindex.TypeKind.POINTER:
         pt = ct.get_pointee()
@@ -85,18 +94,26 @@ def exact_definition(arg):
         return f"{arg.type.spelling} {arg.spelling}"
 
 def cast(arg):
+    """
+    Cast argument ARG to something that LTTng-UST can consume.  Typically,
+    this is used to cast any pointer to void * because pointers are not
+    dereferenced anyway.  Furthermore, array are also cast void *.
+    """
     canon = arg.type.get_canonical()
     if canon.kind == clang.cindex.TypeKind.POINTER:
         return "void *"
     return re.sub(r'\[[0-9]*\]', '*', canon.spelling)
 
-forbiden_list = set()
-
-extra_works = {
-}
-
 def main():
 
+    # Extra works to do for functions.
+    #
+    # Format:
+    #   key = str: function name ; e.g. hipMalloc
+    #   value = str: C code ; e.g. printf("hello\n");
+    extra_works = {
+    }
+
     parser = argparse.ArgumentParser(prog="gen-hip-wrappers")
 
     parser.add_argument("api",
@@ -125,6 +142,9 @@ def main():
 
     args = parser.parse_args()
 
+    # The set of function to not instrument.
+    forbiden_list = set()
+
     if args.ignores:
         with open(args.ignores, "r") as f:
             for ignore in f.read().splitlines():
@@ -148,6 +168,7 @@ $extra_work
 }
 """)
 
+    # Void function are special because they do not return anything ..
     void_fn_tpl = Template("""
 static void lttng_${fn_name}(${fn_arguments})
 {
@@ -160,6 +181,7 @@ $extra_work
 }
 """)
 
+    # Because C++ does not support designated initializer.
     epilogue_tpl = Template("""
 static void lttng_hip_install_wrappers(void)
 {