Add 'projects/rocprofiler-sdk/' from commit 'bf0fad1d5406fbc51403ba1aa9621a9d4a9bce2b'

git-subtree-dir: projects/rocprofiler-sdk
git-subtree-mainline: 50a90550e9
git-subtree-split: bf0fad1d54

projects/rocprofiler-sdk/source/CMakeLists.txt

@@ -0,0 +1,20 @@
+#
+#
+#
+if(ROCPROFILER_BUILD_CODECOV)
+    set(CMAKE_BUILD_TYPE "Coverage")
+endif()
+
+#
+# by default, activate clang-tidy on all code in the source folder. unittest subfolders
+# can add `rocprofiler_deactivate_clang_tidy()` to their CMakeLists.txt to disable
+# clang-tidy linting
+#
+rocprofiler_activate_clang_tidy()
+
+add_subdirectory(include)
+add_subdirectory(lib)
+add_subdirectory(libexec)
+add_subdirectory(bin)
+add_subdirectory(docs)
+add_subdirectory(share)

projects/rocprofiler-sdk/source/bin/CMakeLists.txt

@@ -0,0 +1,27 @@
+#
+#
+#
+
+rocprofiler_activate_clang_tidy()
+
+add_subdirectory(rocprofv3_avail_module)
+
+# Adding main rocprofv3
+configure_file(rocprofv3.py ${PROJECT_BINARY_DIR}/${CMAKE_INSTALL_BINDIR}/rocprofv3 @ONLY)
+
+install(
+    FILES ${PROJECT_BINARY_DIR}/${CMAKE_INSTALL_BINDIR}/rocprofv3
+    DESTINATION ${CMAKE_INSTALL_BINDIR}
+    PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ
+                WORLD_EXECUTE
+    COMPONENT tools)
+
+configure_file(rocprofv3-avail.py
+               ${PROJECT_BINARY_DIR}/${CMAKE_INSTALL_BINDIR}/rocprofv3-avail COPYONLY)
+
+install(
+    FILES ${PROJECT_BINARY_DIR}/${CMAKE_INSTALL_BINDIR}/rocprofv3-avail
+    DESTINATION ${CMAKE_INSTALL_BINDIR}
+    PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ
+                WORLD_EXECUTE
+    COMPONENT tools)

projects/rocprofiler-sdk/source/bin/rocprofv3-avail.py

@@ -0,0 +1,477 @@
+#!/usr/bin/env python3
+
+# MIT License
+#
+# Copyright (c) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+import os
+import argparse
+import sys
+from rocprofv3_avail_module import avail
+
+
+def format_help(formatter, w=120, h=40):
+    """Return a wider HelpFormatter, if possible."""
+    try:
+        kwargs = {"width": w, "max_help_position": h}
+        formatter(None, **kwargs)
+        return lambda prog: formatter(prog, **kwargs)
+    except TypeError:
+        return formatter
+
+
+def strtobool(val):
+    """Convert a string representation of truth to true or false.
+    True values are 'y', 'yes', 't', 'true', 'on', and '1'; false values
+    are 'n', 'no', 'f', 'false', 'off', and '0'.  Raises ValueError if
+    'val' is anything else.
+    """
+    if isinstance(val, (list, tuple)):
+        if len(val) > 1:
+            val_type = type(val).__name__
+            raise ValueError(f"invalid truth value {val} (type={val_type})")
+        else:
+            val = val[0]
+
+    if isinstance(val, bool):
+        return val
+    elif isinstance(val, str) and val.lower() in ("y", "yes", "t", "true", "on", "1"):
+        return True
+    elif isinstance(val, str) and val.lower() in ("n", "no", "f", "false", "off", "0"):
+        return False
+    else:
+        val_type = type(val).__name__
+        raise ValueError(f"invalid truth value {val} (type={val_type})")
+
+
+class booleanArgAction(argparse.Action):
+    def __call__(self, parser, args, value, option_string=None):
+        setattr(args, self.dest, strtobool(value))
+
+
+def parse_arguments(args=None):
+
+    usage_examples = """
+
+%(prog)s, e.g.
+
+    $ rocprofv3-avail [<rocprofv3-avail-option> ...]
+    $ rocprofv3-avail -- avail-hw-counters
+
+"""
+
+    def add_list_options(subparsers):
+        list_command = subparsers.add_parser(
+            "list", help="List options for hw counters, agents and pc-sampling support"
+        )
+        add_parser_bool_argument(list_command, "--pmc", help="List counters")
+        add_parser_bool_argument(
+            list_command, "--agent", help="List basic info of agents"
+        )
+        add_parser_bool_argument(
+            list_command, "--pc-sampling", help="List agents supporting pc-sampling"
+        )
+        list_command.set_defaults(func=process_list)
+
+    def add_info_options(subparsers):
+        info_command = subparsers.add_parser(
+            "info",
+            help="Info options for detailed information of counters, agents, and pc-sampling configurations",
+        )
+
+        info_command.add_argument("--pmc", nargs="*", help="PMC info")
+        info_command.add_argument(
+            "--pc-sampling", nargs="*", help="Detailed PC Sampling info"
+        )
+        info_command.set_defaults(func=process_info)
+
+    def add_pmc_check_options(subparsers):
+        pmc_check_command = subparsers.add_parser(
+            "pmc-check", help="Checking counters collection support on agents"
+        )
+        pmc_check_command.add_argument(
+            "pmc", nargs="*", default=None, help="List of PMC names"
+        )
+        pmc_check_command.set_defaults(func=process_pmc_check)
+
+    def add_parser_bool_argument(gparser, *args, **kwargs):
+        gparser.add_argument(
+            *args,
+            **kwargs,
+            action=booleanArgAction,
+            nargs="?",
+            const=True,
+            type=str,
+            required=False,
+            metavar="BOOL",
+        )
+
+    # Create the parser
+    parser = argparse.ArgumentParser(
+        description="ROCProfilerV3-avail Run Script",
+        usage="%(prog)s [options] ",
+        epilog=usage_examples,
+        formatter_class=format_help(argparse.RawTextHelpFormatter),
+    )
+
+    parser.add_argument(
+        "-d",
+        "--device",
+        help="device index, device on a node to apply the sub-commands on",
+        type=int,
+        default=None,
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command", help="rocprofv3-avail sub commands"
+    )
+
+    add_list_options(subparsers)
+    add_info_options(subparsers)
+    add_pmc_check_options(subparsers)
+
+    return parser.parse_args(args[:])
+
+
+def get_basic_agent_info(info):
+    basic_info = {}
+    req_keys = [
+        "cpu_cores_count",
+        "simd_count",
+        "max_waves_per_simd",
+        "runtime_visibility",
+        "wave_front_size",
+        "num_xcc",
+        "cu_count",
+        "array_count",
+        "num_shader_banks",
+        "simd_arrays_per_engine",
+        "cu_per_simd_array",
+        "simd_per_cu",
+        "gfx_target_version",
+        "max_waves_per_cu",
+        "gpu_id",
+        "workgroup_max_dim",
+        "grid_max_dim",
+        "name",
+        "vendor_name",
+        "product_name",
+        "model_name",
+        "runtime_visibility",
+        "node_id",
+        "logical_node_id",
+        "logical_node_type_id",
+    ]
+    for key in req_keys:
+        basic_info.update({key: info[key]})
+    return basic_info
+
+
+def get_number_columns(max_name_len):
+    total_column_width = 120
+    if sys.stdout.isatty():
+        total_column_width = os.get_terminal_size().columns
+    width = total_column_width / (max_name_len + 1)
+    if width < 1:
+        return 1
+    return int(width)
+
+
+def list_basic_agent(args, list_counters):
+    def print_agent_counter(counters):
+        names_len = [len(counter.name) for counter in counters]
+        names = [
+            "{name:{width}}".format(name=counter.name, width=max(names_len))
+            for counter in counters
+        ]
+        columns = get_number_columns(max(names_len))
+        print("{:30}:\n".format("PMC"))
+        for idx in range(0, len(names), columns):
+            print("{}".format(" ".join(names[idx : (idx + columns)])))
+        print("\n")
+
+    def print_basic_info(info):
+        print("GPU:{}\n".format(info["logical_node_type_id"]))
+        print("\n".join(["{:30}:\t{}".format(key, itr) for key, itr in info.items()]))
+        if not list_counters:
+            print("\n")
+
+    agent_info_map = avail.get_agent_info_map()
+    agent_counters = avail.get_counters()
+
+    for agent, info in dict(sorted(agent_info_map.items())).items():
+        if (
+            info["type"] == 2
+            and args.device is not None
+            and info["logical_node_type_id"] == args.device
+        ):
+            print_basic_info(get_basic_agent_info(info))
+            if list_counters:
+                print_agent_counter(agent_counters[agent])
+            break
+
+        elif info["type"] == 2 and args.device is None:
+            print_basic_info(get_basic_agent_info(info))
+            if list_counters:
+                print_agent_counter(agent_counters[agent])
+
+
+def list_pc_sampling(args):
+    sampling_agents = avail.get_pc_sample_configs()
+    agent_info_map = avail.get_agent_info_map()
+    print("Agents supporting PC Sampling\n")
+    for agent in dict(sorted(sampling_agents.items())).keys():
+        info = agent_info_map[agent]
+        print(
+            "{:8}:\t{}\n{:8}:\t{}".format(
+                "GPU", info["logical_node_type_id"], "Name", info["name"]
+            )
+        )
+        print("\n")
+
+
+def info_pc_sampling(args):
+    sampling_agents = avail.get_pc_sample_configs()
+    agent_info_map = avail.get_agent_info_map()
+    for agent, configs in dict(sorted(sampling_agents.items())).items():
+        info = agent_info_map[agent]
+
+        print(
+            "{:8}:\t{}\n{:8}:\t{}".format(
+                "GPU", info["logical_node_type_id"], "Name", info["name"]
+            )
+        )
+        print("{:8}:".format("configs"))
+        for config in configs:
+            print(config)
+            print("\n")
+        print("\n")
+
+
+def listing(args):
+    def print_agent_counter(counters):
+        names_len = [len(counter.name) for counter in counters]
+        names = [
+            "{name:{width}}".format(name=counter.name, width=max(names_len))
+            for counter in counters
+        ]
+        columns = get_number_columns(max(names_len))
+        print("{:30}:\n".format("PMC"))
+        for idx in range(0, len(names), columns):
+            print("{:30}".format(" ".join(names[idx : (idx + columns)])))
+
+    agent_counters = avail.get_counters()
+    agent_info_map = avail.get_agent_info_map()
+
+    for agent, info in dict(sorted(agent_info_map.items())).items():
+        if (
+            info["type"] == 2
+            and args.device is not None
+            and info["logical_node_type_id"] == args.device
+        ):
+            print(
+                "{:30}:\t{}\n{:30}:\t{}".format(
+                    "GPU", info["logical_node_type_id"], "Name", info["name"]
+                )
+            )
+            print_agent_counter(agent_counters[agent])
+            print("\n")
+            break
+        elif info["type"] == 2 and args.device is None:
+            print(
+                "{:30}:\t{}\n{:30}:\t{}".format(
+                    "GPU", info["logical_node_type_id"], "Name", info["name"]
+                )
+            )
+            print_agent_counter(agent_counters[agent])
+            print("\n")
+
+
+def info_pmc(args):
+    agent_counters = avail.get_counters()
+    agent_info_map = avail.get_agent_info_map()
+
+    def print_pmc_info(args, pmc_counters):
+
+        if not args.pmc:
+            for counter in pmc_counters:
+                print(counter)
+                print("\n")
+        else:
+            for pmc in args.pmc:
+                for counter in pmc_counters:
+                    if pmc == counter.get_as_dict()["Counter_Name"]:
+                        print(counter)
+                        print("\n")
+
+    for agent, info in dict(sorted(agent_info_map.items())).items():
+        if (
+            info["type"] == 2
+            and args.device is not None
+            and info["logical_node_type_id"] == args.device
+        ):
+            print(
+                "{}:{}\n{}:{}".format(
+                    "GPU", info["logical_node_type_id"], "Name", info["name"]
+                )
+            )
+            print_pmc_info(args, agent_counters[agent])
+            break
+        elif info["type"] == 2 and args.device is None:
+            print(
+                "{}:{}\n{}:{}".format(
+                    "GPU", info["logical_node_type_id"], "Name", info["name"]
+                )
+            )
+            print_pmc_info(args, agent_counters[agent])
+
+
+def process_info(args):
+    if args.pmc is None and args.pc_sampling is None:
+        list_basic_agent(args, True)
+    if args.pmc is not None:
+        info_pmc(args)
+    if args.pc_sampling is not None:
+        os.environ["ROCPROFILER_PC_SAMPLING_BETA_ENABLED"] = "on"
+        info_pc_sampling(args)
+
+
+def process_list(args):
+    if args.agent is None and args.pc_sampling is None and args.pmc is None:
+        listing(args)
+    if args.agent:
+        list_basic_agent(args, False)
+    if args.pmc:
+        listing(args)
+    if args.pc_sampling:
+        os.environ["ROCPROFILER_PC_SAMPLING_BETA_ENABLED"] = "on"
+        list_pc_sampling(args)
+
+
+def process_pmc_check(args):
+    def get_device_agent(device_id):
+        for agent, info in agent_info_map.items():
+            if info["type"] == 2 and info["logical_node_type_id"] == device_id:
+                return agent
+        avail.fatal_error("Invalid device id : {}".format(device_id))
+
+    def get_gpu_agents():
+        agent_ids = []
+        for agent, info in agent_info_map.items():
+            if info["type"] == 2:
+                agent_ids.append(agent)
+        return agent_ids
+
+    def get_counter_handle(counter_name):
+        agent_counters = avail.get_counters()
+        for agent, counters in agent_counters.items():
+            for counter in counters:
+                if counter.get_as_dict()["Counter_Name"] == counter_name:
+                    return counter.counter_handle
+        avail.fatal_error("Invalid counter name")
+
+    def get_counter_names(pmc_list, agent):
+        agent_counters = avail.get_counters()
+        counter_names = []
+        for pmc in pmc_list:
+            for counter in agent_counters[agent]:
+                if counter.counter_handle == pmc:
+                    counter_names.append(counter.name)
+        return counter_names
+
+    def get_logical_node_type_id(agent_id):
+        for agent, info in agent_info_map.items():
+            if info["type"] == 2 and info["id"]["handle"] == agent_id:
+                return info["logical_node_type_id"]
+
+    def process_qualifiers(pmc):
+        res = pmc.split(":")
+        if len(res) > 2:
+            avail.fatal_error("Invalid format for pmc-check")
+
+        if len(res) == 2:
+            qualifiers_list = []
+            qualifiers = res[1]
+            if "device" not in qualifiers:
+                avail.fatal_error("Incorrect input format for device index")
+            qualifiers = qualifiers.split(",")
+            for qualifier in qualifiers:
+                qualifiers_list.append(dict([qualifier.split("=")]))
+            return (res[0], qualifiers_list)
+
+        return (res[0], None)
+
+    if not args.pmc:
+        avail.fatal_error("Provide counter to check")
+
+    device_pmc = {}
+    agent_info_map = avail.get_agent_info_map()
+
+    for pmc in args.pmc:
+        counter, qualifiers = process_qualifiers(pmc)
+        if qualifiers is None:
+            if args.device is not None:
+                agent_handle = get_device_agent(args.device)
+                if agent_handle not in device_pmc.keys():
+                    device_pmc.setdefault(agent_handle, [])
+                device_pmc[agent_handle].append(get_counter_handle(counter))
+            else:
+                agent_ids = get_gpu_agents()
+                for agent_handle in agent_ids:
+                    if agent_handle not in device_pmc.keys():
+                        device_pmc.setdefault(agent_handle, [])
+                    device_pmc[agent_handle].append(get_counter_handle(counter))
+        else:
+            for itr in qualifiers:
+                agent_handle = get_device_agent(int(itr["device"]))
+                if agent_handle not in device_pmc.keys():
+                    device_pmc.setdefault(agent_handle, [])
+                device_pmc[agent_handle].append(get_counter_handle(counter))
+
+    if avail.check_pmc(device_pmc) is True:
+        for agent, pmc in device_pmc.items():
+            device_id = get_logical_node_type_id(agent)
+            pmc_names = get_counter_names(pmc, agent)
+            print(
+                "Following input counters can be collected together on GPU:{}\t{}".format(
+                    device_id, "\t".join(pmc_names)
+                )
+            )
+
+
+def main(argv=None):
+    ROCPROFV3_AVAIL_DIR = os.path.dirname(os.path.realpath(__file__))
+    ROCM_DIR = os.path.dirname(ROCPROFV3_AVAIL_DIR)
+    ROCPROF_LIST_AVAIL_TOOL_LIBRARY = (
+        f"{ROCM_DIR}/lib/rocprofiler-sdk/librocprofv3-list-avail.so"
+    )
+    os.environ["ROCPROFILER_METRICS_PATH"] = f"{ROCM_DIR}/share/rocprofiler-sdk"
+    avail.loadLibrary.libname = os.environ.get(
+        "ROCPROF_LIST_AVAIL_TOOL_LIBRARY", ROCPROF_LIST_AVAIL_TOOL_LIBRARY
+    )
+    args = parse_arguments(argv)
+    if args.command:
+        args.func(args)
+
+
+if __name__ == "__main__":
+    ec = main(sys.argv[1:])
+    sys.exit(ec)

projects/rocprofiler-sdk/source/bin/rocprofv3_avail_module/CMakeLists.txt

@@ -0,0 +1,37 @@
+# MIT License
+#
+# Copyright (c) 2023-2025 Advanced Micro Devices, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+set(PACKAGE_OUTPUT_DIR
+    ${PROJECT_BINARY_DIR}/${CMAKE_INSTALL_BINDIR}/rocprofv3_avail_module)
+
+set(ROCPROFV3_AVAIL_SOURCES __init__.py avail.py)
+
+foreach(_FILE ${ROCPROFV3_AVAIL_SOURCES})
+    configure_file(${CMAKE_CURRENT_LIST_DIR}/${_FILE} ${PACKAGE_OUTPUT_DIR}/${_FILE}
+                   COPYONLY)
+    install(
+        FILES ${PACKAGE_OUTPUT_DIR}/${_FILE}
+        DESTINATION ${CMAKE_INSTALL_BINDIR}/rocprofv3_avail_module
+        PERMISSIONS OWNER_READ OWNER_WRITE OWNER_EXECUTE GROUP_READ GROUP_EXECUTE
+                    WORLD_READ WORLD_EXECUTE
+        COMPONENT tools)
+endforeach()

projects/rocprofiler-sdk/source/bin/rocprofv3_avail_module/__init__.py

@@ -0,0 +1,23 @@
+# MIT License
+#
+# Copyright (c) 2023-2025 Advanced Micro Devices, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+from __future__ import absolute_import

projects/rocprofiler-sdk/source/bin/rocprofv3_avail_module/avail.py

@@ -0,0 +1,495 @@
+#!/usr/bin/env python3
+
+# MIT License
+#
+# Copyright (c) 2024-2025 Advanced Micro Devices, Inc. All rights reserved.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+
+import sys
+import ctypes
+import json
+
+
+def fatal_error(msg, exit_code=1):
+    sys.stderr.write(f"Fatal error: {msg}\n")
+    sys.stderr.flush()
+    sys.exit(exit_code)
+
+
+def build_counter_string(obj):
+    counter_str = "\n".join(
+        ["{:20}:\t{}".format(key, itr) for key, itr in obj.get_as_dict().items()]
+    )
+
+    counter_str += "\n" + "{:20}:\t".format("Dimensions")
+    counter_str += " ".join(dim.__str__() for dim in obj.dimensions)
+    return counter_str
+
+
+class dimension:
+    columns = ["Dimension_Id", "Dimension_Name", "Dimension_Instances"]
+
+    def __init__(self, dimension_id, dimension_name, dimension_instances):
+        self.id = dimension_id
+        self.name = dimension_name
+        self.instances = dimension_instances
+
+    def get_as_dict(self):
+        return dict(zip((self.columns), [self.id, self.name, self.instances]))
+
+    def __str__(self):
+        dimension = "{}[0:{}]".format(
+            self.get_as_dict()["Dimension_Name"],
+            self.get_as_dict()["Dimension_Instances"] - 1,
+        )
+        return dimension
+
+
+class counter:
+
+    columns = ["Counter_Name", "Description"]
+
+    def __init__(
+        self,
+        counter_handle,
+        counter_name,
+        counter_description,
+        counter_dimensions,
+        is_hw_constant,
+    ):
+        self.name = counter_name
+        self.counter_handle = counter_handle
+        self.description = counter_description
+        self.dimensions = counter_dimensions
+        self.is_hw_constant = is_hw_constant
+
+    def get_as_dict(self):
+        return dict(zip((self.columns), [self.name, self.description]))
+
+    def __str__(self):
+        return "\n".join(
+            ["{:20}:\t{}".format(key, itr) for key, itr in self.get_as_dict().items()]
+        )
+
+
+class derived_counter(counter):
+
+    columns = ["Counter_Name", "Description", "Expression"]
+
+    def __init__(
+        self,
+        counter_handle,
+        counter_name,
+        counter_description,
+        counter_expression,
+        counter_dimensions,
+        is_hw_constant,
+    ):
+        super().__init__(
+            counter_handle,
+            counter_name,
+            counter_description,
+            counter_dimensions,
+            is_hw_constant,
+        )
+        self.expression = counter_expression
+
+    def get_as_dict(self):
+        return dict(zip((self.columns), [self.name, self.description, self.expression]))
+
+    def __str__(self):
+        return build_counter_string(self)
+
+
+class basic_counter(counter):
+
+    columns = ["Counter_Name", "Description", "Block"]
+
+    def __init__(
+        self,
+        counter_handle,
+        counter_name,
+        counter_description,
+        counter_block,
+        counter_dimensions,
+        is_hw_constant,
+    ):
+        super().__init__(
+            counter_handle,
+            counter_name,
+            counter_description,
+            counter_dimensions,
+            is_hw_constant,
+        )
+        self.block = counter_block
+
+    def get_as_dict(self):
+        return dict(zip((self.columns), [self.name, self.description, self.block]))
+
+    def __str__(self):
+        return build_counter_string(self)
+
+
+class pc_config:
+
+    columns = ["Method", "Unit", "Min_Interval", "Max_Interval", "Flags"]
+
+    def __init__(self, config_method, config_unit, min_interval, max_interval, flags):
+
+        self.method = self.get_method_string(config_method.value)
+        self.unit = self.get_unit_string(config_unit.value)
+        self.min_interval = min_interval
+        self.max_interval = max_interval
+        self.flags = flags
+
+    def __str__(self):
+
+        return "\n".join(
+            [
+                "   {:20}:\t{}".format(
+                    key,
+                    itr if key == "Method" or key == "Unit" else self.get_value(key, itr),
+                )
+                for key, itr in self.get_as_dict().items()
+            ]
+        )
+
+    @staticmethod
+    def get_value(key, itr):
+        if key == "Min_Interval" or key == "Max_Interval":
+            return itr.value
+        elif key == "Flags":
+            if itr.value == 1:
+                return "interval pow2"
+            else:
+                return "none"
+        else:
+            fatal_error("Incorrect key")
+
+    @staticmethod
+    def get_method_string(key):
+        method_map = {1: "stochastic", 2: "host_trap"}
+        return method_map[key]
+
+    @staticmethod
+    def get_unit_string(key):
+        unit_map = {1: "instructions", 2: "cycle", 3: "time"}
+        return unit_map[key]
+
+    def get_as_dict(self):
+
+        return dict(
+            zip(
+                (self.columns),
+                [
+                    self.method,
+                    self.unit,
+                    self.min_interval,
+                    self.max_interval,
+                    self.flags,
+                ],
+            )
+        )
+
+
+class loadLibrary:
+    libname = None
+    c_lib = None
+
+
+def get_library():
+
+    get_library.libname = None
+    if loadLibrary.c_lib is None:
+        loadLibrary.c_lib = ctypes.CDLL(loadLibrary.libname)
+    return loadLibrary.c_lib
+
+
+def get_string_value(str_ptr):
+    return ctypes.cast(str_ptr, ctypes.c_char_p).value.decode("utf-8")
+
+
+def get_agent_info(agent_handle):
+    lib = get_library()
+    lib.agent_info.argtypes = [ctypes.c_ulong, ctypes.POINTER(ctypes.c_char_p)]
+    agent_info_str = ctypes.c_char_p()
+    lib.agent_info(agent_handle, ctypes.byref(agent_info_str))
+    return json.loads(agent_info_str.value.decode("utf-8"))
+
+
+def get_number_of_counters(agent_handle):
+    lib = get_library()
+    lib.get_number_of_counters.restype = ctypes.c_ulong
+    lib.get_number_of_counters.argtypes = [ctypes.c_ulong]
+    return lib.get_number_of_agent_counters(agent_handle)
+
+
+def get_number_agents():
+    lib = get_library()
+    lib.get_number_of_agents.restype = ctypes.c_ulong
+    return lib.get_number_of_agents()
+
+
+def get_agent_handles():
+    lib = get_library()
+    num_agents = get_number_agents()
+    lib.agent_handles.argtypes = [ctypes.c_ulong * num_agents, ctypes.c_ulong]
+    agent_handles_arr = (ctypes.c_ulong * num_agents)()
+    lib.agent_handles(agent_handles_arr, num_agents)
+    return list(agent_handles_arr)
+
+
+def get_agent_info_map():
+    agent_info_map = {}
+    agents = get_agent_handles()
+    for agent in agents:
+        agent_info_map[agent] = get_agent_info(agent)
+
+    return agent_info_map
+
+
+def get_number_of_agent_counters(agent_handle):
+    lib = get_library()
+    lib.get_number_of_agent_counters.argtypes = [ctypes.c_ulong]
+    return lib.get_number_of_agent_counters(agent_handle)
+
+
+def get_agent_counter_handles(agent_handle):
+    lib = get_library()
+    num_counters = get_number_of_agent_counters(agent_handle)
+    lib.agent_counter_handles.argtypes = [
+        ctypes.c_ulong * num_counters,
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+    ]
+    counter_handles = (ctypes.c_ulong * num_counters)()
+    lib.agent_counter_handles(counter_handles, agent_handle, num_counters)
+    return list(counter_handles)
+
+
+def get_dimensions(counter_handle):
+    lib = get_library()
+    lib.get_number_of_dimensions.argtypes = [ctypes.c_ulong]
+    lib.get_number_of_dimensions.restype = ctypes.c_ulong
+    num_dims = lib.get_number_of_dimensions(counter_handle)
+
+    lib.counter_dimension_ids.argtypes = [
+        ctypes.c_ulong,
+        ctypes.c_ulong * num_dims,
+        ctypes.c_uint,
+    ]
+    dims_ids = (ctypes.c_ulong * num_dims)()
+    lib.counter_dimension.argtypes = [
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+        ctypes.POINTER(ctypes.c_char_p),
+        ctypes.POINTER(ctypes.c_uint),
+    ]
+    lib.counter_dimension_ids(counter_handle, dims_ids, num_dims)
+    dimensions = []
+    for dim_id in list(dims_ids):
+        dimension_name = ctypes.c_char_p()
+        dimension_instance = ctypes.c_uint()
+        lib.counter_dimension(
+            counter_handle,
+            dim_id,
+            ctypes.byref(dimension_name),
+            ctypes.byref(dimension_instance),
+        )
+        dim = dimension(
+            dim_id, get_string_value(dimension_name), dimension_instance.value
+        )
+        dimensions.append(dim)
+    return dimensions
+
+
+def get_counters():
+    agent_counters = {}
+    agents = get_agent_handles()
+    agent_counters = {}
+    agent_info_map = get_agent_info_map()
+    for agent in agents:
+        if agent_info_map[agent]["type"] != 2:
+            continue
+        agent_counters.setdefault(agent, [])
+        counters = get_agent_counter_handles(agent)
+        if counters:
+            for counter_id in list(counters):
+                counter_info = get_counter_info(counter_id)
+                agent_counters[agent].append(counter_info)
+    return agent_counters
+
+
+def get_pc_sample_configs():
+    agent_pc_sample_config = {}
+    agents = get_agent_handles()
+
+    for agent in agents:
+        configs = get_pc_sample_config(agent)
+        if len(configs) > 0:
+            agent_pc_sample_config[agent] = configs
+
+    return agent_pc_sample_config
+
+
+def get_counter_info(counter_handle):
+    lib = get_library()
+    lib.counter_info.argtypes = [
+        ctypes.c_ulong,
+        ctypes.POINTER(ctypes.c_char_p),
+        ctypes.POINTER(ctypes.c_char_p),
+        ctypes.POINTER(ctypes.c_uint),
+        ctypes.POINTER(ctypes.c_uint),
+    ]
+    counter_name = ctypes.c_char_p()
+    counter_description = ctypes.c_char_p()
+    is_derived = ctypes.c_uint()
+    is_hw_constant = ctypes.c_uint()
+    lib.counter_info(
+        counter_handle,
+        ctypes.byref(counter_name),
+        ctypes.byref(counter_description),
+        ctypes.byref(is_derived),
+        ctypes.byref(is_hw_constant),
+    )
+
+    if is_derived.value == 1:
+        lib.counter_expression.argtypes = [
+            ctypes.c_ulong,
+            ctypes.POINTER(ctypes.c_char_p),
+        ]
+        expression = ctypes.c_char_p()
+        lib.counter_expression(counter_handle, ctypes.byref(expression))
+        dimensions = get_dimensions(counter_handle)
+        return derived_counter(
+            counter_handle,
+            get_string_value(counter_name),
+            get_string_value(counter_description),
+            get_string_value(expression),
+            dimensions,
+            is_hw_constant,
+        )
+
+    elif not is_hw_constant.value:
+        lib.counter_block.argtypes = [ctypes.c_ulong, ctypes.POINTER(ctypes.c_char_p)]
+        block = ctypes.c_char_p()
+        lib.counter_block(counter_handle, ctypes.byref(block))
+        dimensions = get_dimensions(counter_handle)
+        return basic_counter(
+            counter_handle,
+            get_string_value(counter_name),
+            get_string_value(counter_description),
+            get_string_value(block),
+            dimensions,
+            is_hw_constant,
+        )
+    else:
+        return counter(
+            counter_handle,
+            get_string_value(counter_name),
+            get_string_value(counter_description),
+            [],
+            is_hw_constant.value,
+        )
+
+
+def get_number_of_pc_sample_configs(agent_handle):
+    lib = get_library()
+    lib.get_number_of_pc_sample_configs.argtypes = [ctypes.c_ulong]
+    lib.get_number_of_pc_sample_configs.restype = ctypes.c_ulong
+    return lib.get_number_of_pc_sample_configs(agent_handle)
+
+
+def get_pc_sample_config(agent_handle):
+    lib = get_library()
+    num_configs = get_number_of_pc_sample_configs(agent_handle)
+    lib.pc_sample_config.argtypes = [
+        ctypes.c_ulong,
+        ctypes.c_ulong,
+        ctypes.POINTER(ctypes.c_ulong),
+        ctypes.POINTER(ctypes.c_ulong),
+        ctypes.POINTER(ctypes.c_ulong),
+        ctypes.POINTER(ctypes.c_ulong),
+        ctypes.POINTER(ctypes.c_ulong),
+    ]
+    pc_configs = []
+
+    for config in range(0, num_configs):
+        method = (ctypes.c_ulong)()
+        unit = (ctypes.c_ulong)()
+        max_interval = (ctypes.c_ulong)()
+        min_interval = (ctypes.c_ulong)()
+        flags = (ctypes.c_ulong)()
+        lib.pc_sample_config(
+            agent_handle,
+            config,
+            ctypes.byref(method),
+            ctypes.byref(unit),
+            ctypes.byref(min_interval),
+            ctypes.byref(max_interval),
+            flags,
+        )
+        pc_configs.append(
+            pc_config(
+                method,
+                unit,
+                min_interval,
+                max_interval,
+                flags,
+            )
+        )
+    return pc_configs
+
+
+def check_pmc(agent_counter):
+    lib = get_library()
+
+    def get_counter_names(counter_ids):
+
+        counter_names = []
+        for counter_id in counter_ids:
+            counter = get_counter_info(counter_id)
+            if counter.counter_handle == counter_id:
+                counter_names.append(counter.name)
+        return counter_names
+
+    def get_agent_name(agent_id):
+        agent_info_map = get_agent_info_map()
+        for agent, info in agent_info_map.items():
+            if agent == agent_id:
+                return info["name"]
+
+    for agent, counter_ids in agent_counter.items():
+        num_counters = len(counter_ids)
+        counters = (ctypes.c_ulong * num_counters)(*counter_ids)
+        lib.is_counter_set.argtypes = [
+            ctypes.c_ulong * num_counters,
+            ctypes.c_ulong,
+            ctypes.c_ulong,
+        ]
+        lib.is_counter_set.restype = ctypes.c_bool
+        if lib.is_counter_set(counters, agent, num_counters) is False:
+            fatal_error(
+                "{} not collected on agent {}".format(
+                    " ".join(get_counter_names(counter_ids)), get_agent_name(agent)
+                )
+            )
+    return True

projects/rocprofiler-sdk/source/docs/.gitignore

@@ -0,0 +1,7 @@
+/build*
+/_build
+/_doxygen
+/.gitinfo
+/*.dox
+/.sass-cache
+/_toc.yml

projects/rocprofiler-sdk/source/docs/CMakeLists.txt

@@ -0,0 +1,146 @@
+#
+#
+
+if(NOT ROCPROFILER_BUILD_DOCS)
+    return()
+endif()
+
+set(PACKAGE_NAME ${PROJECT_NAME})
+
+include(FetchContent)
+
+if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.24)
+    cmake_policy(SET CMP0135 NEW)
+endif()
+
+set(DOCS_WD ${CMAKE_CURRENT_BINARY_DIR})
+set(CONDA_ROOT ${PROJECT_BINARY_DIR}/external/miniconda)
+
+find_program(SHELL_CMD NAMES bash sh REQUIRED)
+find_program(CHMOD_CMD NAMES chmod)
+
+if(NOT EXISTS ${PROJECT_BINARY_DIR}/external/miniconda.sh)
+    message(
+        STATUS
+            "Downloading https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh"
+        )
+    file(
+        DOWNLOAD
+        https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
+        ${PROJECT_BINARY_DIR}/external/miniconda.sh
+        STATUS MINICONDA_DOWNLOAD_RET
+        INACTIVITY_TIMEOUT 60
+        SHOW_PROGRESS)
+
+    if(NOT MINICONDA_DOWNLOAD_RET EQUAL 0)
+        message(
+            FATAL_ERROR
+                "Download to ${PROJECT_BINARY_DIR}/external/miniconda.sh from https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh failed"
+            )
+    endif()
+endif()
+
+function(DOCS_EXECUTE_PROCESS)
+    string(REPLACE ";" " " _MSG "${ARGN}")
+    message(STATUS "[rocprofiler][docs] Executing: ${_MSG}")
+
+    execute_process(
+        COMMAND ${CMAKE_COMMAND} -E env HOME=${DOCS_WD} ${ARGN}
+        RESULT_VARIABLE _RET
+        OUTPUT_VARIABLE _OUT
+        ERROR_VARIABLE _ERR
+        WORKING_DIRECTORY ${PROJECT_BINARY_DIR}/external)
+
+    if(NOT _RET EQUAL 0)
+        message(STATUS "docs command failed: ${_RET}")
+        message(STATUS "stderr:\n${_ERR}")
+        message(STATUS "stdout:\n${_OUT}")
+        string(REPLACE ";" " " _CMD "${ARGN}")
+        message(FATAL_ERROR "command failure: ${_CMD}")
+    endif()
+endfunction()
+
+include(ProcessorCount)
+processorcount(ROCP_NUM_PROCS)
+if(NOT ROCP_NUM_PROCS EQUAL 0)
+    set(DOCS_BUILD_JOBS -j${ROCP_NUM_PROCS})
+    message(STATUS "Using ${ROCP_NUM_PROCS} jobs for docs build")
+endif()
+
+file(
+    WRITE "${CMAKE_CURRENT_BINARY_DIR}/build-docs.sh"
+    "#!${SHELL_CMD}
+
+set -e
+set -x
+
+HOME=${DOCS_WD}
+export HOME
+
+env
+
+if [ ! -d '${CONDA_ROOT}' ]; then
+    chmod +x ${PROJECT_BINARY_DIR}/external/miniconda.sh
+    ${PROJECT_BINARY_DIR}/external/miniconda.sh -b -p ${CONDA_ROOT}
+fi
+
+PATH=${PROJECT_BINARY_DIR}/external/miniconda/bin:\${PATH}
+export PATH
+
+source ${CONDA_ROOT}/bin/activate
+
+conda config --set always_yes yes
+conda update -n base conda
+
+if [ ! -d '${CONDA_ROOT}/envs/rocprofiler-docs' ]; then
+    ${CONDA_ROOT}/bin/conda env create -n rocprofiler-docs -f ${CMAKE_CURRENT_LIST_DIR}/environment.yml
+fi
+
+which python
+
+conda activate rocprofiler-docs
+
+which python
+
+python -m pip install -r ${CMAKE_CURRENT_LIST_DIR}/sphinx/requirements.txt
+
+WORK_DIR=${PROJECT_SOURCE_DIR}/source/docs
+SOURCE_DIR=${PROJECT_SOURCE_DIR}
+
+cd \${SOURCE_DIR}
+
+cmake -B build-docs \${SOURCE_DIR} -DROCPROFILER_INTERNAL_BUILD_DOCS=ON
+
+cd \${WORK_DIR}
+
+cmake -DSOURCE_DIR=\${SOURCE_DIR} -P \${WORK_DIR}/generate-doxyfile.cmake
+
+mkdir -p _doxygen/rocprofiler-sdk
+mkdir -p _doxygen/roctx
+
+doxygen rocprofiler-sdk.dox
+doxygen rocprofiler-sdk-roctx.dox
+
+doxysphinx build \${WORK_DIR} \${WORK_DIR}/_build/html \${WORK_DIR}/_doxygen/rocprofiler-sdk/html
+doxysphinx build \${WORK_DIR} \${WORK_DIR}/_build/html \${WORK_DIR}/_doxygen/roctx/html
+
+make html SPHINXOPTS=\"--keep-going -n -q -T ${DOCS_BUILD_JOBS}\"
+
+rm -rf ${PROJECT_SOURCE_DIR}/build-docs
+")
+
+if(CHMOD_CMD)
+    docs_execute_process(${CHMOD_CMD} +x ${CMAKE_CURRENT_BINARY_DIR}/build-docs.sh)
+    add_custom_target(docs ${CMAKE_COMMAND} -E env HOME=${DOCS_WD}
+                           ${CMAKE_CURRENT_BINARY_DIR}/build-docs.sh)
+else()
+    add_custom_target(docs ${CMAKE_COMMAND} -E env HOME=${DOCS_WD} ${SHELL_CMD}
+                           ${CMAKE_CURRENT_BINARY_DIR}/build-docs.sh)
+endif()
+
+install(
+    DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/_build/html/
+    DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/html/${PACKAGE_NAME}
+    COMPONENT docs
+    OPTIONAL USE_SOURCE_PERMISSIONS FILES_MATCHING
+    PATTERN "*")

projects/rocprofiler-sdk/source/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

projects/rocprofiler-sdk/source/docs/README.md

@@ -0,0 +1,19 @@
+# ROCprofiler Documentation
+
+## Build Instructions
+
+1. Install conda
+    - `wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh`
+    - `bash miniconda.sh -b -p /opt/conda`
+    - `export PATH=${PATH}:/opt/conda`
+2. Install conda environment
+    - `source activate`
+    - `conda env create -n rocprofiler-docs -f environment.yml`
+    - `conda activate rocprofiler-docs`
+3. Build the docs
+    - `../scripts/update-docs.sh`
+    - HTML docs will be located in `_build/html`
+
+## Developer Information
+
+If you create a new page, add the name of the new markdown file (without extension) to the [index.md](index.md) file.

projects/rocprofiler-sdk/source/docs/_toc.yml.in

@@ -0,0 +1,90 @@
+# Anywhere {branch} is used, the branch name will be substituted.
+# These comments will also be removed.
+defaults:
+  numbered: false
+  maxdepth: 4
+
+root: index
+subtrees:
+  - caption: Install
+    entries:
+    - file: install/installation
+  - caption: How to
+    entries:
+    - file: how-to/samples
+      title: Samples
+    - file: how-to/using-rocprofv3
+    - file: how-to/using-rocpd-output-format
+    - file: how-to/using-rocprofv3-avail
+    - file: how-to/using-rocprofiler-sdk-roctx
+    - file: how-to/using-rocprofv3-with-mpi
+    - file: how-to/using-rocprofv3-with-openmp
+    - file: how-to/using-pc-sampling
+    - file: how-to/using-thread-trace
+  - caption: API reference
+    entries:
+    - file: api-reference/tool_library
+      title: Tool library
+    - file: api-reference/intercept_table
+      title: Runtime intercept tables
+    - file: api-reference/buffered_services
+      title: Buffered services
+    - file: api-reference/callback_services
+      title: Callback tracing services
+    - file: api-reference/counter_collection_services
+      title: Counter collection services
+    - file: api-reference/pc_sampling
+      title: PC sampling
+    - file: api-reference/thread_trace
+      title: Thread trace and ROCprof Trace Decoder
+    - file: api-reference/rocprofiler-sdk_api_reference
+      subtrees:
+      - entries:
+        - file: api-reference/rocprofiler-sdk_api/modules
+          subtrees:
+          - entries:
+            - file: api-reference/rocprofiler-sdk_api/modules/agent_information
+            - file: api-reference/rocprofiler-sdk_api/modules/buffer_handling
+            - file: api-reference/rocprofiler-sdk_api/modules/buffer_tracing
+            - file: api-reference/rocprofiler-sdk_api/modules/callback_tracing
+            - file: api-reference/rocprofiler-sdk_api/modules/context_management
+            - file: api-reference/rocprofiler-sdk_api/modules/counter_config
+            - file: api-reference/rocprofiler-sdk_api/modules/counters
+            - file: api-reference/rocprofiler-sdk_api/modules/device_counting_service
+            - file: api-reference/rocprofiler-sdk_api/modules/dispatch_counting_service
+            - file: api-reference/rocprofiler-sdk_api/modules/external_correalation
+            - file: api-reference/rocprofiler-sdk_api/modules/intercept_table
+            - file: api-reference/rocprofiler-sdk_api/modules/internal_threading_management
+            - file: api-reference/rocprofiler-sdk_api/modules/ompt_registration
+            - file: api-reference/rocprofiler-sdk_api/modules/pc_sampling_service
+            - file: api-reference/rocprofiler-sdk_api/modules/thread_trace
+            - file: api-reference/rocprofiler-sdk_api/modules/tool_registration
+        - file: api-reference/rocprofiler-sdk_api/global_data_structures_topics_files
+          subtrees:
+            - entries:
+              - file: api-reference/rocprofiler-sdk_api/global_data_structures_topics_files/global_basic_data_types
+              - file: _doxygen/rocprofiler-sdk/html/topics
+              - file: _doxygen/rocprofiler-sdk/html/annotated
+              - file: _doxygen/rocprofiler-sdk/html/files
+    - file: api-reference/rocprofiler-sdk-roctx_api_reference
+      subtrees:
+      - entries:
+        - file: api-reference/rocprofiler-sdk-roctx_api/roctx_modules
+          subtrees:
+          - entries:
+            - file: api-reference/rocprofiler-sdk-roctx_api/roctx_modules/markers
+            - file: api-reference/rocprofiler-sdk-roctx_api/roctx_modules/ranges
+            - file: api-reference/rocprofiler-sdk-roctx_api/roctx_modules/profiler-control
+            - file: api-reference/rocprofiler-sdk-roctx_api/roctx_modules/naming-utilities
+        - file: api-reference/rocprofiler-sdk-roctx_api/global_roctx_data_structures_topics_files
+          subtrees:
+          - entries:
+            - file: api-reference/rocprofiler-sdk-roctx_api/global_roctx_data_structures_topics_files/global_roctx_basic_data_types
+            - file: _doxygen/roctx/html/topics
+            - file: _doxygen/roctx/html/files
+  - caption: Conceptual
+    entries:
+    - file: conceptual/comparing-with-legacy-tools
+  - caption: License
+    entries:
+    - file: license

projects/rocprofiler-sdk/source/docs/api-reference/buffered_services.rst

@@ -0,0 +1,245 @@
+
+.. meta::
+    :description: ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software
+    :keywords: ROCprofiler-SDK API reference, Buffered services API
+
+.. _buffered-services:
+
+ROCprofiler-SDK buffered services
+=================================
+
+In the buffered approach, the internal (background) thread sends callbacks for batches of records.
+Supported buffer record categories are enumerated in ``rocprofiler_buffer_category_t`` category field and supported buffer tracing services are enumerated in  ``rocprofiler_buffer_tracing_kind_t``. Configuring
+a buffered tracing service requires buffer creation. Flushing the buffer implicitly or explicitly invokes a callback to the tool, which provides an array of one or more buffer records.
+To flush a buffer explicitly, use ``rocprofiler_flush_buffer`` function.
+
+Subscribing to buffer tracing services
+--------------------------------------
+
+During tool initialization, the tool configures callback tracing using ``rocprofiler_configure_buffer_tracing_service``
+function. However, before invoking ``rocprofiler_configure_buffer_tracing_service``, the tool must create a buffer for the tracing records as shown in the following section.
+
+Creating a buffer
+-----------------
+
+.. code-block:: cpp
+
+    rocprofiler_status_t
+    rocprofiler_create_buffer(rocprofiler_context_id_t        context,
+                              size_t                          size,
+                              size_t                          watermark,
+                              rocprofiler_buffer_policy_t     policy,
+                              rocprofiler_buffer_tracing_cb_t callback,
+                              void*                           callback_data,
+                              rocprofiler_buffer_id_t*        buffer_id);
+
+Here are the parameters required to create a buffer:
+
+- ``size``: Size of the buffer in bytes, which is rounded up to the nearest
+  memory page size (defined by ``sysconf(_SC_PAGESIZE)``). The default memory page size on Linux
+  is 4096 bytes (4 KB).
+
+- ``watermark``: Specifies the number of bytes at which the buffer should be flushed. To flush the buffer, the records in the buffer must invoke the ``callback`` parameter to deliver the records to the tool. For example, for a buffer of size 4096 bytes with the watermark set to 48 bytes, six 8-byte records can be placed in the
+  buffer before ``callback`` is invoked. However, every 64-byte record that is placed in the
+  buffer will trigger a flush. It is safe to set the ``watermark`` to any value between
+  zero and the buffer size.
+
+- ``policy``: Specifies the behavior when a record is larger than the
+  amount of free space in the current buffer. For example, for a buffer of size 4000 bytes with the watermark set to 4000 bytes and 3998 bytes populated with records, the ``policy`` dictates how to handle an incoming record greater than 2 bytes. If the environment variable ``ROCPROFILER_BUFFER_POLICY_DISCARD`` is enabled, all records greater than 2 bytes are dropped until the tool _explicitly_ flushes the buffer using ``rocprofiler_flush_buffer`` function call whereas, if the environment variable ``ROCPROFILER_BUFFER_POLICY_LOSSLESS`` is enabled, the current buffer is swapped out for an empty buffer and placed in the new buffer while the former (full) buffer is _implicitly_ flushed.
+
+- ``callback``: Invoked to flush the buffer.
+
+- ``callback_data``: Value passed as one of the arguments to the ``callback`` function.
+
+- ``buffer_id``: Output parameter for the function call to contain a
+  non-zero handle field after successful buffer creation.
+
+Creating a dedicated thread for buffer callbacks
+------------------------------------------------
+
+By default, all buffers use the same (default) background thread created by ROCprofiler-SDK to
+invoke their callback. However, ROCprofiler-SDK provides an interface to allow the tools to create an additional background thread for one or more of their buffers.
+
+To create callback threads for buffers, use ``rocprofiler_create_callback_thread`` function:
+
+.. code-block:: cpp
+
+    rocprofiler_status_t
+    rocprofiler_create_callback_thread(rocprofiler_callback_thread_t* cb_thread_id);
+
+To assign buffers to that callback thread, use ``rocprofiler_assign_callback_thread`` function:
+
+.. code-block:: cpp
+
+    rocprofiler_status_t
+    rocprofiler_assign_callback_thread(rocprofiler_buffer_id_t       buffer_id,
+                                       rocprofiler_callback_thread_t cb_thread_id);
+
+**Example:**
+
+.. code-block:: cpp
+
+    {
+        // create a context
+        auto context_id = rocprofiler_context_id_t{0};
+        rocprofiler_create_context(&context_id);
+
+        // create a buffer associated with the context
+        auto buffer_id  = rocprofiler_buffer_id_t{};
+        rocprofiler_create_buffer(context_id, ..., &buffer_id);
+
+        // specify that a new callback thread should be created and provide
+        // and assign the identifier for it to the "thr_id" variable
+        auto thr_id = rocprofiler_callback_thread_t{};
+        rocprofiler_create_callback_thread(&thr_id);
+
+        // assign the buffer callback to be delivered on this thread
+        rocprofiler_assign_callback_thread(buffer_id, thr_id);
+    }
+
+Configuring buffer tracing services
+-----------------------------------
+
+To configure buffer tracing services, use:
+
+.. code-block:: cpp
+
+    rocprofiler_status_t
+    rocprofiler_configure_buffer_tracing_service(rocprofiler_context_id_t          context_id,
+                                                 rocprofiler_buffer_tracing_kind_t kind,
+                                                 rocprofiler_tracing_operation_t*  operations,
+                                                 size_t                            operations_count,
+                                                 rocprofiler_buffer_id_t           buffer_id);
+
+Here are the parameters required to configure buffer tracing services:
+
+- ``kind``: A high-level specification of the services to be traced. This parameter is also known as "domain".
+  Domain examples include, but not limited to, the HIP API, HSA API, and kernel dispatches.
+
+- ``operations``: For each domain, there are often various ``operations`` that can be used to restrict the callbacks to a subset within the domain. For domains corresponding to APIs, the ``operations`` are the functions
+  composing the API. To trace all operations in a domain, set the ``operations`` and ``operations_count``
+  parameters to ``nullptr`` and ``0`` respectively. To restrict the tracing domain to a subset
+  of operations, the tool library must specify a C-array of type ``rocprofiler_tracing_operation_t`` for ``operations`` and size of the array for the ``operations_count`` parameter.
+
+Similar to the ``rocprofiler_configure_callback_tracing_service``,
+``rocprofiler_configure_buffer_tracing_service`` returns an error if a buffer service for the specified context
+and domain is configured more than once.
+
+**Example:**
+
+.. code-block:: cpp
+
+    {
+        auto ctx = rocprofiler_context_id_t{};
+        // ... creation of context, etc. ...
+
+        // buffer parameters
+        constexpr auto KB          = 1024;  // 1024 bytes
+        constexpr auto buffer_size = 16 * KB;
+        constexpr auto watermark   = 15 * KB;
+        constexpr auto policy      = ROCPROFILER_BUFFER_POLICY_LOSSLESS;
+
+        // buffer handle
+        auto buffer_id = rocprofiler_buffer_id_t{};
+
+        // create a buffer associated with the context
+        rocprofiler_create_buffer(
+            context_id, buffer_size, watermark, policy, callback_func, nullptr, &buffer_id);
+
+        // configure HIP runtime API function records to be placed in buffer
+        rocprofiler_configure_buffer_tracing_service(
+            ctx, ROCPROFILER_BUFFER_TRACING_HIP_RUNTIME_API, nullptr, 0, buffer_id);
+
+        // configure kernel dispatch records to be placed in buffer
+        // (more than one service can use the same buffer)
+        rocprofiler_configure_buffer_tracing_service(
+            ctx, ROCPROFILER_BUFFER_TRACING_KERNEL_DISPATCH, nullptr, 0, buffer_id);
+
+        // ... etc. ...
+    }
+
+Buffer tracing callback function
+--------------------------------
+
+Here is the buffer tracing callback function:
+
+.. code-block:: cpp
+
+    typedef void (*rocprofiler_buffer_tracing_cb_t)(rocprofiler_context_id_t      context,
+                                                    rocprofiler_buffer_id_t       buffer_id,
+                                                    rocprofiler_record_header_t** headers,
+                                                    size_t                        num_headers,
+                                                    void*                         data,
+                                                    uint64_t                      drop_count);
+
+The ``rocprofiler_record_header_t`` data type contains the following information:
+
+- ``category`` (``rocprofiler_buffer_category_t``): The ``category`` is used to classify the buffer record. For all
+  services configured via ``rocprofiler_configure_buffer_tracing_service``, the ``category`` is equal to the value of ``ROCPROFILER_BUFFER_CATEGORY_TRACING``. The other available categories are ``ROCPROFILER_BUFFER_CATEGORY_PC_SAMPLING`` and ``ROCPROFILER_BUFFER_CATEGORY_COUNTERS``.
+
+- ``kind``: The ``kind`` field is dependent on the ``category``. For example, for ``category`` ``ROCPROFILER_BUFFER_CATEGORY_TRACING``, the value of ``kind`` depicts the tracing type such as HSA core API in ``ROCPROFILER_BUFFER_TRACING_HSA_CORE_API``.
+
+- ``payload``: The ``payload`` is casted after the category and kind have been determined.
+
+.. code-block:: cpp
+
+    {
+        if(header->category == ROCPROFILER_BUFFER_CATEGORY_TRACING &&
+            header->kind == ROCPROFILER_BUFFER_TRACING_HIP_RUNTIME_API)
+        {
+            auto* record =
+                static_cast<rocprofiler_buffer_tracing_hip_api_record_t*>(header->payload);
+
+            // ... etc. ...
+        }
+    }
+
+**Example:**
+
+.. code-block:: cpp
+
+    void
+    buffer_callback_func(rocprofiler_context_id_t      context,
+                         rocprofiler_buffer_id_t       buffer_id,
+                         rocprofiler_record_header_t** headers,
+                         size_t                        num_headers,
+                         void*                         user_data,
+                         uint64_t                      drop_count)
+    {
+        for(size_t i = 0; i < num_headers; ++i)
+        {
+            auto* header = headers[i];
+
+            if(header->category == ROCPROFILER_BUFFER_CATEGORY_TRACING &&
+               header->kind == ROCPROFILER_BUFFER_TRACING_HIP_RUNTIME_API)
+            {
+                auto* record =
+                    static_cast<rocprofiler_buffer_tracing_hip_api_record_t*>(header->payload);
+
+                // ... etc. ...
+            }
+            else if(header->category == ROCPROFILER_BUFFER_CATEGORY_TRACING &&
+                    header->kind == ROCPROFILER_BUFFER_TRACING_KERNEL_DISPATCH)
+            {
+                auto* record =
+                    static_cast<rocprofiler_buffer_tracing_kernel_dispatch_record_t*>(header->payload);
+
+                // ... etc. ...
+            }
+            else
+            {
+                throw std::runtime_error{"unhandled record header category + kind"};
+            }
+        }
+    }
+
+Buffer tracing record
+---------------------
+
+Unlike callback tracing records, there is no common set of data for each buffer tracing record. However,
+many buffer tracing records contain a ``kind`` and an ``operation`` field.
+You can obtain the value for the ``kind`` of tracing using ``rocprofiler_query_buffer_tracing_kind_name`` function and the value for the ``operation`` specific to a tracing kind using the ``rocprofiler_query_buffer_tracing_kind_operation_name``
+function. You can also iterate over all the buffer tracing ``kinds`` and ``operations`` for each tracing kind using the
+``rocprofiler_iterate_buffer_tracing_kinds`` and ``rocprofiler_iterate_buffer_tracing_kind_operations`` functions.
+
+The buffer tracing record data types are available in the ``rocprofiler-sdk/buffer_tracing.h`` header.

projects/rocprofiler-sdk/source/docs/api-reference/callback_services.rst

@@ -0,0 +1,342 @@
+
+.. meta::
+    :description: ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software
+    :keywords: ROCprofiler-SDK API reference, ROCprofiler-SDK callback services, Callback services API
+
+.. _rocprofiler_sdk_callback_tracing_services:
+
+ROCprofiler-SDK callback tracing services
+=========================================
+
+Callback tracing services provide immediate callbacks to a tool on the current CPU thread on the occurrence of an event.
+For example, when tracing an API function such as ``hipSetDevice``, callback tracing invokes a user-specified callback
+before and after the traced function executes on the thread invoking the API function.
+
+Subscribing to callback tracing services
+----------------------------------------
+
+During tool initialization, tools configure callback tracing using:
+
+.. code-block:: cpp
+
+    rocprofiler_status_t
+    rocprofiler_configure_callback_tracing_service(rocprofiler_context_id_t            context_id,
+                                                   rocprofiler_callback_tracing_kind_t kind,
+                                                   rocprofiler_tracing_operation_t*    operations,
+                                                   size_t                              operations_count,
+                                                   rocprofiler_callback_tracing_cb_t   callback,
+                                                   void*                               callback_args);
+
+Here are the parameters required to configure callback tracing services:
+
+- ``kind``: A high-level specification of the services to be traced. This parameter is also known as "domain".
+  Domain examples include, but not limited to, the HIP API, HSA API, and kernel dispatches.
+
+- ``operations``: For each domain, there are often various ``operations`` that can be used to restrict the callbacks to a subset within the domain. For domains corresponding to APIs, the ``operations`` are the functions
+  composing the API. To trace all operations in a domain, set the ``operations`` and ``operations_count``
+  parameters to ``nullptr`` and ``0`` respectively. To restrict the tracing domain to a subset
+  of operations, the tool library must specify a C-array of type ``rocprofiler_tracing_operation_t`` for ``operations`` and size of the array for the ``operations_count`` parameter.
+
+``rocprofiler_configure_callback_tracing_service`` returns an error if a callback service for the specified context and domain is configured more than once.
+
+**Example:** To trace only two functions within
+the HIP runtime API, ``hipGetDevice`` and ``hipSetDevice``:
+
+.. code-block:: cpp
+
+    {
+        auto ctx = rocprofiler_context_id_t{};
+        // ... creation of context, etc. ...
+
+        // array of operations (i.e. API functions)
+        auto operations = std::array<rocprofiler_tracing_operation_t, 2>{
+            ROCPROFILER_HIP_RUNTIME_API_ID_hipSetDevice,
+            ROCPROFILER_HIP_RUNTIME_API_ID_hipGetDevice
+        };
+
+        rocprofiler_configure_callback_tracing_service(ctx,
+                                                       ROCPROFILER_CALLBACK_TRACING_HIP_RUNTIME_API,
+                                                       operations.data(),
+                                                       operations.size(),
+                                                       callback_func,
+                                                       nullptr);
+        // ... etc. ...
+    }
+
+The following code returns error ``ROCPROFILER_STATUS_ERROR_SERVICE_ALREADY_CONFIGURED`` as the callback service is already configured:
+
+.. code-block:: cpp
+
+    {
+        auto ctx = rocprofiler_context_id_t{};
+        // ... creation of context, etc. ...
+
+        // array of operations (i.e. API functions)
+        auto operations = std::array<rocprofiler_tracing_operation_t, 2>{
+            ROCPROFILER_HIP_RUNTIME_API_ID_hipSetDevice,
+            ROCPROFILER_HIP_RUNTIME_API_ID_hipGetDevice
+        };
+
+        for(auto op : operations)
+        {
+            // after the first iteration, returns ROCPROFILER_STATUS_ERROR_SERVICE_ALREADY_CONFIGURED
+            rocprofiler_configure_callback_tracing_service(ctx,
+                                                           ROCPROFILER_CALLBACK_TRACING_HIP_RUNTIME_API,
+                                                           &op,
+                                                           1,
+                                                           callback_func,
+                                                           nullptr);
+        }
+
+        // ... etc. ...
+    }
+
+Callback tracing callback function
+----------------------------------
+
+Here is the callback tracing callback function:
+
+.. code-block:: cpp
+
+    typedef void (*rocprofiler_callback_tracing_cb_t)(rocprofiler_callback_tracing_record_t record,
+                                                      rocprofiler_user_data_t*              user_data,
+                                                      void* callback_data)
+
+The parameters ``record`` and ``user_data`` are discussed here:
+
+- ``record``: Contains the information to uniquely identify a tracing record type. Here is the definition:
+
+  .. code-block:: cpp
+
+      typedef struct rocprofiler_callback_tracing_record_t
+      {
+        rocprofiler_context_id_t            context_id;
+        rocprofiler_thread_id_t             thread_id;
+        rocprofiler_correlation_id_t        correlation_id;
+        rocprofiler_callback_tracing_kind_t kind;
+        uint32_t                            operation;
+        rocprofiler_callback_phase_t        phase;
+        void*                               payload;
+      } rocprofiler_callback_tracing_record_t;
+
+  The underlying type of ``payload`` field is typically unique to a domain and, less frequently, an operation.
+  For example, for the ``ROCPROFILER_CALLBACK_TRACING_HIP_RUNTIME_API`` and ``ROCPROFILER_CALLBACK_TRACING_HIP_COMPILER_API``,
+  the payload must be casted to ``rocprofiler_callback_tracing_hip_api_data_t*``, which contains the arguments
+  to the function and the return value when exiting the function. The payload field is a valid
+  pointer only during the invocation of the callback function(s).
+
+- ``user_data``: Stores data in between callback phases. This value is unique for every
+  instance of an operation. For example, for a tool library to store the timestamp of the
+  ``ROCPROFILER_CALLBACK_PHASE_ENTER`` phase for the ensuing ``ROCPROFILER_CALLBACK_PHASE_EXIT`` callback,
+  the data can be stored using:
+
+  .. code-block:: cpp
+
+      void
+      callback_func(rocprofiler_callback_tracing_record_t record,
+                    rocprofiler_user_data_t*              user_data,
+                    void*                                 cb_data)
+      {
+          auto ts = rocprofiler_timestamp_t{};
+          rocprofiler_get_timestamp(&ts);
+
+          if(record.phase == ROCPROFILER_CALLBACK_PHASE_ENTER)
+          {
+              user_data->value = ts;
+          }
+          else if(record.phase == ROCPROFILER_CALLBACK_PHASE_EXIT)
+          {
+              auto delta_ts = (ts - user_data->value);
+              // ... etc. ...
+          }
+          else
+          {
+              // ... etc. ...
+          }
+      }
+
+  The `callback_data` is passed to `rocprofiler_configure_callback_tracing_service` as the value of `callback_args` to :ref:`subscribe to callback tracing services <rocprofiler_sdk_callback_tracing_services>`.
+
+Callback tracing record
+-----------------------
+
+To obtain the name of the ``kind`` of tracing, you can use ``rocprofiler_query_callback_tracing_kind_name`` function and to obtain the name of an ``operation`` specific to a tracing kind, use ``rocprofiler_query_callback_tracing_kind_operation_name``
+function. To iterate over all the callback tracing kinds and operations for each tracing kind, use ``rocprofiler_iterate_callback_tracing_kinds`` and ``rocprofiler_iterate_callback_tracing_kind_operations`` functions.
+
+Lastly, for a specified ``rocprofiler_callback_tracing_record_t`` object, ROCprofiler-SDK supports generically iterating over the arguments of the payload field for many domains. Within the ``rocprofiler_callback_tracing_record_t`` object, the domain-specific information is available in
+an opaque ``void* payload``.
+The data types generally follow the naming convention of ``rocprofiler_callback_tracing_<DOMAIN>_data_t``. For example, for the tracing kinds ``ROCPROFILER_BUFFER_TRACING_HSA_{CORE,AMD_EXT,IMAGE_EXT,FINALIZE_EXT}_API``,
+cast the payload to ``rocprofiler_callback_tracing_hsa_api_data_t*``:
+
+.. code-block:: cpp
+
+    void
+    callback_func(rocprofiler_callback_tracing_record_t record,
+                  rocprofiler_user_data_t*              user_data,
+                  void*                                 cb_data)
+    {
+        static auto hsa_domains = std::unordered_set<rocprofiler_buffer_tracing_kind_t>{
+            ROCPROFILER_BUFFER_TRACING_HSA_CORE_API,
+            ROCPROFILER_BUFFER_TRACING_HSA_AMD_EXT_API,
+            ROCPROFILER_BUFFER_TRACING_HSA_IMAGE_EXT_API,
+            ROCPROFILER_BUFFER_TRACING_HSA_FINALIZER_API};
+
+        if(hsa_domains.count(record.kind) > 0)
+        {
+            auto* payload = static_cast<rocprofiler_callback_tracing_hsa_api_data_t*>(record.payload);
+
+            hsa_status_t status = payload->retval.hsa_status_t_retval;
+            if(record.phase == ROCPROFILER_CALLBACK_PHASE_EXIT && status != HSA_STATUS_SUCCESS)
+            {
+                const char* _kind = nullptr;
+                const char* _operation = nullptr;
+
+                rocprofiler_query_callback_tracing_kind_name(record.kind, &_kind, nullptr);
+                rocprofiler_query_callback_tracing_kind_operation_name(
+                    record.kind, record.operation, &_operation, nullptr);
+
+                // message that
+                fprintf(stderr, "[domain=%s] %s returned a non-zero exit code: %i\n", _kind, _operation, status);
+            }
+        }
+        else if(record.phase == ROCPROFILER_CALLBACK_PHASE_EXIT)
+        {
+            auto delta_ts = (ts - user_data->value);
+            // ... etc. ...
+        }
+        else
+        {
+            // ... etc. ...
+        }
+    }
+
+**Example:** Iterating over all the callback tracing kinds and operations for each tracing kind using ``rocprofiler_iterate_callback_tracing_kind_operation_args``:
+
+.. code-block:: cpp
+
+    int
+    print_args(rocprofiler_callback_tracing_kind_t domain_idx,
+               uint32_t                            op_idx,
+               uint32_t                            arg_num,
+               const void* const                   arg_value_addr,
+               int32_t                             arg_indirection_count,
+               const char*                         arg_type,
+               const char*                         arg_name,
+               const char*                         arg_value_str,
+               int32_t                             arg_dereference_count,
+               void*                               data)
+    {
+        if(arg_num == 0)
+        {
+            const char* _kind      = nullptr;
+            const char* _operation = nullptr;
+
+            rocprofiler_query_callback_tracing_kind_name(domain_idx, &_kind, nullptr);
+            rocprofiler_query_callback_tracing_kind_operation_name(
+                domain_idx, op_idx, &_operation, nullptr);
+
+            fprintf(stderr, "\n[%s] %s\n", _kind, _operation);
+        }
+
+        char* _arg_type = abi::__cxa_demangle(arg_type, nullptr, nullptr, nullptr);
+
+        fprintf(stderr, "    %u: %-18s %-16s = %s\n", arg_num, _arg_type, arg_name, arg_value_str);
+
+        free(_arg_type);
+
+        // unused in example
+        (void) arg_value_addr;
+        (void) arg_indirection_count;
+        (void) arg_dereference_count;
+        (void) data;
+
+        return 0;
+    }
+
+    void
+    callback_func(rocprofiler_callback_tracing_record_t record,
+                  rocprofiler_user_data_t*              user_data,
+                  void*                                 cb_data)
+    {
+        if(record.phase == ROCPROFILER_CALLBACK_PHASE_EXIT &&
+           record.kind == ROCPROFILER_CALLBACK_TRACING_HIP_RUNTIME_API &&
+           (record.operation == ROCPROFILER_HIP_RUNTIME_API_ID_hipLaunchKernel ||
+            record.operation == ROCPROFILER_HIP_RUNTIME_API_ID_hipMemcpyAsync))
+        {
+            rocprofiler_iterate_callback_tracing_kind_operation_args(
+                                 record, print_args, record.phase, nullptr));
+        }
+    }
+
+**Sample output:**
+
+.. code-block:: console
+
+    [HIP_RUNTIME_API] hipLaunchKernel
+        0: void const*        function_address = 0x219308
+        1: rocprofiler_dim3_t numBlocks        = {z=1, y=310, x=310}
+        2: rocprofiler_dim3_t dimBlocks        = {z=1, y=32, x=32}
+        3: void**             args             = 0x7ffe6d8dd3c0
+        4: unsigned long      sharedMemBytes   = 0
+        5: hipStream_t*      stream           = 0x17b40c0
+
+    [HIP_RUNTIME_API] hipMemcpyAsync
+        0: void*              dst              = 0x7f06c7bbb010
+        1: void const*        src              = 0x7f0698800000
+        2: unsigned long      sizeBytes        = 393625600
+        3: hipMemcpyKind      kind             = DeviceToHost
+        4: hipStream_t*      stream           = 0x25dfcf0
+
+Code object tracing
+-------------------
+
+The code object tracing service is a critical component for obtaining information regarding
+asynchronous activity on the GPU. The ``rocprofiler_callback_tracing_code_object_load_data_t``
+payload (kind=``ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT``, operation=``ROCPROFILER_CODE_OBJECT_LOAD``)
+provides a unique identifier for a bundle of one or more GPU kernel symbols that are loaded
+for a specific GPU agent. For example, if your application leverages a multi-GPU system
+consisting of four Vega20 GPUs and four MI100 GPUs, at least eight code objects will be loaded: one code
+object for each GPU. Each code object will be associated with a set of kernel symbols.
+The ``rocprofiler_callback_tracing_code_object_kernel_symbol_register_data_t`` payload
+(kind=``ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT``, operation=``ROCPROFILER_CODE_OBJECT_DEVICE_KERNEL_SYMBOL_REGISTER``)
+provides a globally unique identifier for the specific kernel symbol along with the kernel name and
+several other static properties of the kernel such as scratch size, scalar general purpose register count, and so on.
+
+.. note::
+    The kernel identifiers for two identical kernel symbols with the same properties (kernel name, scratch size, and so on) that are part of similar code objects loaded for different GPU agents will still be unique. Furthermore, the identifier for a code object and its kernel symbols after being unloaded and then
+    reloaded, will also be unique.
+
+Here is the general sequence of events when a code object is loaded and unloaded:
+
+1. Callback: load code object
+   - kind= ``ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT``
+   - operation= ``ROCPROFILER_CODE_OBJECT_LOAD``
+   - phase= ``ROCPROFILER_CALLBACK_PHASE_LOAD``
+2. Callback: load kernel symbol
+   - kind= ``ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT``
+   - operation= ``ROCPROFILER_CODE_OBJECT_DEVICE_KERNEL_SYMBOL_REGISTER``
+   - phase= ``ROCPROFILER_CALLBACK_PHASE_LOAD``
+   - Repeats for each kernel symbol in code object
+3. Execute application
+4. Callback: unload kernel symbol
+   - kind= ``ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT``
+   - operation= ``ROCPROFILER_CODE_OBJECT_DEVICE_KERNEL_SYMBOL_REGISTER``
+   - phase= ``ROCPROFILER_CALLBACK_PHASE_UNLOAD``
+   - Repeats for each kernel symbol in code object
+5. Callback: unload code object
+   - kind= ``ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT``
+   - operation= ``ROCPROFILER_CODE_OBJECT_LOAD``
+   - phase= ``ROCPROFILER_CALLBACK_PHASE_UNLOAD``
+
+.. note::
+    ROCprofiler-SDK doesn't provide an interface to query information outside of the
+    code object tracing service. If you wish to associate kernel names with kernel tracing records,
+    the tool must be configured to create a copy of the relevant information when the code objects and
+    kernel symbol are loaded. However, any constant string fields like ``const char* kernel_name``
+    don't need to be copied as these are guaranteed to be valid pointers until after ROCprofiler-SDK finalization.
+    If a tool decides to delete its copy of the data associated with a code object or kernel symbol
+    identifier when the code object and kernel symbols are unloaded, it is highly recommended to flush
+    all buffers that might contain references to that code object or kernel symbol identifier before
+    deleting the associated data.
+
+For a sample of code object tracing, see `samples/code_object_tracing <https://github.com/ROCm/rocprofiler-sdk/tree/amd-mainline/samples/code_object_tracing>`_.

projects/rocprofiler-sdk/source/docs/api-reference/counter_collection_services.rst

@@ -0,0 +1,443 @@
+.. meta::
+    :description: ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software
+    :keywords: ROCprofiler-SDK API reference, ROCprofiler-SDK counter collection
+
+.. _rocprofiler_sdk_counter_collection_services:
+
+ROCprofiler-SDK counter collection services
+===========================================
+
+There are two modes of counter collection service:
+
+- **Dispatch counting**: In this mode, counters are collected on a per-kernel launch basis. This mode is useful for collecting highly detailed counters for a specific kernel execution in isolation. Note that dispatch counting allows only a single kernel to execute in hardware at a time.
+
+- **Device counting**: In this mode, counters are collected on a device level. This mode is useful for collecting device level counters not tied to a specific kernel execution, which encompasses collecting counter values for a specific time range.
+
+This topic explains how to setup dispatch and device counting and use common counter collection APIs. For details on the APIs including the less commonly used counter collection APIs, see the API library. For fully functional examples of both dispatch and device counting, see `Samples <https://github.com/ROCm/rocprofiler-sdk/tree/amd-mainline/samples>`_.
+
+Definitions
+-----------
+
+**Profile Config**: A configuration to specify the counters to be collected on an agent. This must be supplied to various counter collection APIs to initiate collection of counter data. Profiles are agent-specific and can't be used on different agents.
+
+**Counter ID**: Unique Id (per-architecture) that specifies the counter. The counter Id can be used to fetch counter information such as its name or expression.
+
+**Instance ID**: Unique record Id that encodes the counter Id and dimension for a collected value.
+
+**Dimension**: Dimensions help to provide context to the raw counter values by specifying the hardware register that is the source of counter collection such as a shader engine. All counter values have dimension data encoded in their instance Id, which allows you to extract the values for individual dimensions using functions in the counter interface. The following dimensions are supported:
+
+.. code-block:: c
+
+    ROCPROFILER_DIMENSION_XCC,            ///< XCC dimension of result
+    ROCPROFILER_DIMENSION_AID,            ///< AID dimension of result
+    ROCPROFILER_DIMENSION_SHADER_ENGINE,  ///< SE dimension of result
+    ROCPROFILER_DIMENSION_AGENT,          ///< Agent dimension
+    ROCPROFILER_DIMENSION_SHADER_ARRAY,   ///< Number of shader arrays
+    ROCPROFILER_DIMENSION_WGP,            ///< Number of workgroup processors
+    ROCPROFILER_DIMENSION_INSTANCE,       ///< From unspecified hardware register
+
+Using the Counter Collection Service
+------------------------------------
+
+The setup for dispatch and device counting is similar with only minor changes needed to adapt code from one to another. Here are the steps required to configure the counter collection services:
+
+tool_init() setup
++++++++++++++++++++
+
+Similar to tracing services, you must create a context and a buffer to collect the output when initializing the tool.
+
+.. code-block:: cpp
+
+    rocprofiler_context_id_t ctx{0};
+    rocprofiler_buffer_id_t buff;
+    ROCPROFILER_CALL(rocprofiler_create_context(&ctx), "context creation failed");
+    ROCPROFILER_CALL(rocprofiler_create_buffer(ctx,
+                                                4096,
+                                                2048,
+                                                ROCPROFILER_BUFFER_POLICY_LOSSLESS,
+                                                buffered_callback, // Callback to process data
+                                                user_data,
+                                                &buff),
+                        "buffer creation failed");
+
+
+After creating a context and buffer to store results in ``tool_init``, it is highly recommended but not mandatory for you to construct the profiles for each agent, containing the counters for collection. Profile creation should be avoided in the time critical dispatch counting callback as it involves validating if the counters can be collected on the agent. After profile setup, you can set up the collection service for dispatch or device counting. To set up either dispatch or device counting (only one can be used at a time), use:
+
+.. code-block:: cpp
+
+    /* For Dispatch Counting */
+    // Setup the dispatch profile counting service. This service will trigger the dispatch_callback
+    // when a kernel dispatch is enqueued into the HSA queue. The callback will specify what
+    // counters to collect by returning a profile config id.
+    ROCPROFILER_CALL(rocprofiler_configure_buffer_dispatch_counting_service(
+                         ctx, buff, dispatch_callback, nullptr),
+                     "Could not setup buffered service");
+
+    /* For Agent Counting */
+    // set_profile is a callback that is use to select the profile to use when
+    // the context is started. It is called at every rocprofiler_ctx_start() call.
+    ROCPROFILER_CALL(rocprofiler_configure_device_counting_service(
+                         ctx, buff, agent_id, set_profile, nullptr),
+                     "Could not setup buffered service");
+
+
+Profile Setup
+-------------
+
+1. The first step in constructing a counter collection profile is to find the GPU agents on the machine. You must create a profile for each set of counters to be collected on every agent on the machine. You can use ``rocprofiler_query_available_agents`` to find agents on the system. The following example collects all GPU agents on the device and stores them in the vector agents:
+
+.. code-block:: cpp
+
+    std::vector<rocprofiler_agent_v0_t> agents;
+
+    // Callback used by rocprofiler_query_available_agents to return
+    // agents on the device. This can include CPU agents as well. We
+    // select GPU agents only (i.e. type == ROCPROFILER_AGENT_TYPE_GPU)
+    rocprofiler_query_available_agents_cb_t iterate_cb = [](rocprofiler_agent_version_t agents_ver,
+                                                            const void**                agents_arr,
+                                                            size_t                      num_agents,
+                                                            void*                       udata) {
+        if(agents_ver != ROCPROFILER_AGENT_INFO_VERSION_0)
+            throw std::runtime_error{"unexpected rocprofiler agent version"};
+        auto* agents_v = static_cast<std::vector<rocprofiler_agent_v0_t>*>(udata);
+        for(size_t i = 0; i < num_agents; ++i)
+        {
+            const auto* agent = static_cast<const rocprofiler_agent_v0_t*>(agents_arr[i]);
+            if(agent->type == ROCPROFILER_AGENT_TYPE_GPU) agents_v->emplace_back(*agent);
+        }
+        return ROCPROFILER_STATUS_SUCCESS;
+    };
+
+    // Query the agents, only a single callback is made that contains a vector
+    // of all agents.
+    ROCPROFILER_CALL(
+        rocprofiler_query_available_agents(ROCPROFILER_AGENT_INFO_VERSION_0,
+                                           iterate_cb,
+                                           sizeof(rocprofiler_agent_t),
+                                           const_cast<void*>(static_cast<const void*>(&agents))),
+        "query available agents");
+
+2. To identify the counters supported by an agent, query the available counters with ``rocprofiler_iterate_agent_supported_counters``. Here is an example of a single agent returning the available counters in ``gpu_counters``:
+
+.. code-block:: cpp
+
+    std::vector<rocprofiler_counter_id_t> gpu_counters;
+
+    // Iterate all the counters on the agent and store them in gpu_counters.
+    ROCPROFILER_CALL(rocprofiler_iterate_agent_supported_counters(
+                         agent,
+                         [](rocprofiler_agent_id_t,
+                            rocprofiler_counter_id_t* counters,
+                            size_t                    num_counters,
+                            void*                     user_data) {
+                             std::vector<rocprofiler_counter_id_t>* vec =
+                                 static_cast<std::vector<rocprofiler_counter_id_t>*>(user_data);
+                             for(size_t i = 0; i < num_counters; i++)
+                             {
+                                 vec->push_back(counters[i]);
+                             }
+                             return ROCPROFILER_STATUS_SUCCESS;
+                         },
+                         static_cast<void*>(&gpu_counters)),
+                     "Could not fetch supported counters");
+
+3. ``rocprofiler_counter_id_t`` is a handle to a counter. To fetch information about the counter such as its name, use ``rocprofiler_query_counter_info``:
+
+.. code-block:: cpp
+
+    for(auto& counter : gpu_counters)
+    {
+        // Contains name and other attributes about the counter.
+        // See API documentation for more info on the contents of this struct.
+        rocprofiler_counter_info_v0_t info;
+        ROCPROFILER_CALL(
+            rocprofiler_query_counter_info(
+                counter, ROCPROFILER_COUNTER_INFO_VERSION_0, static_cast<void*>(&info)),
+            "Could not query info for counter");
+    }
+
+
+4. After identifying the counters to be collected, construct a profile by passing a list of these counters to ``rocprofiler_create_counter_config``.
+
+.. code-block:: cpp
+
+    // Create and return the profile
+    rocprofiler_counter_config_id_t profile;
+    ROCPROFILER_CALL(rocprofiler_create_counter_config(
+                         agent, counters_array, counters_array_count, &profile),
+                     "Could not construct profile cfg");
+
+
+5. You can use the created profile for both dispatch and agent counter collection services.
+
+.. note::
+    Points to note on profile behavior:
+
+    - Profile created is *only valid* for the agent it was created for.
+    - Profiles are immutable. To collect a new counter set, construct a new profile.
+    - A single profile can be used multiple times on the same agent.
+    - Counter Ids supplied to ``rocprofiler_create_counter_config`` are *agent-specific* and can't be used to construct profiles for other agents.
+
+Dispatch Counting Callback
+--------------------------
+
+When a kernel is dispatched, a dispatch callback is issued to the tool to allow selection of counters to be collected for the dispatch by supplying a profile.
+
+.. code-block:: cpp
+
+    void
+    dispatch_callback(rocprofiler_dispatch_counting_service_data_t dispatch_data,
+                      rocprofiler_counter_config_id_t*             config,
+                      rocprofiler_user_data_t* user_data,
+                      void* /*callback_data_args*/)
+
+``dispatch_data`` contains information about the dispatch being launched such as its name. ``config`` is used by the tool to specify the profile, which allows counter collection for the dispatch. If no profile is supplied, no counters are collected for this dispatch. ``user_data`` contains user data supplied to ``rocprofiler_configure_buffered_dispatch_profile_counting_service``.
+
+Agent Set Profile Callback
+--------------------------
+
+This callback is invoked after the context starts and allows the tool to specify the profile to be used.
+
+.. code-block:: cpp
+
+    void
+    set_profile(rocprofiler_context_id_t               context_id,
+                rocprofiler_agent_id_t                 agent,
+                rocprofiler_device_counting_agent_cb_t set_config,
+                void*)
+
+The profile to be used for this agent is specified by calling ``set_config(agent, profile)``.
+
+Buffered callback
+++++++++++++++++++
+
+Data from collected counter values is returned through a buffered callback. The buffered callback routines are similar for dispatch and device counting except that some data such as kernel launch Ids is not available in device counting mode. Here is a sample iteration to print out counter collection data:
+
+.. code-block:: cpp
+
+    for(size_t i = 0; i < num_headers; ++i)
+    {
+        auto* header = headers[i];
+        if(header->category == ROCPROFILER_BUFFER_CATEGORY_COUNTERS &&
+           header->kind == ROCPROFILER_COUNTER_RECORD_PROFILE_COUNTING_DISPATCH_HEADER)
+        {
+            // Print the returned counter data.
+            auto* record =
+                static_cast<rocprofiler_dispatch_counting_service_record_t*>(header->payload);
+            ss << "[Dispatch_Id: " << record->dispatch_info.dispatch_id
+               << " Kernel_ID: " << record->dispatch_info.kernel_id
+               << " Corr_Id: " << record->correlation_id.internal << ")]\n";
+        }
+        else if(header->category == ROCPROFILER_BUFFER_CATEGORY_COUNTERS &&
+                header->kind == ROCPROFILER_COUNTER_RECORD_VALUE)
+        {
+            // Print the returned counter data.
+            auto* record = static_cast<rocprofiler_counter_record_t*>(header->payload);
+            rocprofiler_counter_id_t counter_id = {.handle = 0};
+
+            rocprofiler_query_record_counter_id(record->id, &counter_id);
+
+            ss << "  (Dispatch_Id: " << record->dispatch_id << " Counter_Id: " << counter_id.handle
+               << " Record_Id: " << record->id << " Dimensions: [";
+
+            for(auto& dim : counter_dimensions(counter_id))
+            {
+                size_t pos = 0;
+                rocprofiler_query_record_dimension_position(record->id, dim.id, &pos);
+                ss << "{" << dim.name << ": " << pos << "},";
+            }
+            ss << "] Value [D]: " << record->counter_value << "),";
+        }
+    }
+
+Counter Definitions
+-------------------
+
+Counters are defined in yaml format in the ``counter_defs.yaml`` file. The counter definition has the following format:
+
+.. code-block:: yaml
+
+    counter_name:       # Counter name
+      architectures:
+        gfx90a:         # Architecture name
+          block:        # Block information (SQ/etc)
+          event:        # Event ID (used by AQLProfile to identify counter register)
+          expression:   # Formula for the counter (if derived counter)
+          description:  # Per-arch description (optional)
+        gfx1010:
+           ...
+      description:      # Description of the counter
+
+You can separately define the counters for different architectures as shown in the preceding example for gfx90a and gfx1010. If two or more architectures share the same block, event, or expression definition, they can be specified together using "/" delimiter ("gfx90a/gfx1010:"). Hardware metrics have the elements block, event, and description defined. Derived metrics have the element expression defined and can't have block or event defined.
+
+Derived Metrics
+---------------
+
+Derived metrics are expressions performing computation on collected hardware metrics. These expressions produce result similar to a real hardware counter.
+
+.. code-block:: yaml
+
+    GPU_UTIL:
+      architectures:
+        gfx942/gfx941/gfx10/gfx1010/gfx1030/gfx1031/gfx11/gfx1032/gfx1102/gfx906/gfx1100/gfx1101/gfx940/gfx908/gfx90a/gfx9:
+          expression: 100*GRBM_GUI_ACTIVE/GRBM_COUNT
+      description: Percentage of the time that GUI is active
+
+In the preceding example, ``GPU_UTIL`` is a derived metric that uses a mathematic expression to calculate the utilization rate of the GPU using values of two GRBM hardware counters ``GRBM_GUI_ACTIVE`` and ``GRBM_COUNT``. Expressions support the standard set of math operators (/,*,-,+) along with a set of special functions such as reduce and accumulate.
+
+Reduce Function
+++++++++++++++++
+
+.. code-block:: yaml
+
+    Expression: 100*reduce(GL2C_HIT,sum)/(reduce(GL2C_HIT,sum)+reduce(GL2C_MISS,sum))
+
+The reduce function reduces counter values across all dimensions such as shader engine, SIMD, and so on, to produce a single output value. This helps to collect and compare values across the entire device. Here are the common reduction operations:
+
+- ``sum``: Sums to create a single output. For example, ``reduce(GL2C_HIT,sum)`` sums all ``GL2C_HIT`` hardware register values.
+- ``avr``: Calculates the average across all dimensions.
+- ``min``: Selects minimum value across all dimensions.
+- ``max``: Selects the maximum value across all dimensions.
+
+.. code-block:: yaml
+
+    expression: reduce(X,sum,[DIMENSION_XCC])
+
+Reduce() also supports dimension wise reduction, when provided dimensions in 3rd parameter. In the expression above, if ``X`` has two dimensions ``DIMENSION_XCC``, ``DIMENSION_SHADER_ARRAY``, and ``DIMENSION_WGP``, the reduce happens across counter values where ``DIMENSION_SHADER_ARRAY`` and ``DIMENSION_WGP`` dimensions are same as shown below.
+
+Let's say DIM sizes of XCC, SHADER_ARRAY(SH), WGP be 2, 4, 4 respectively.
+
+Raw Counter Data in 3D space:
+
+#### XCC[0]:
+
+.. code-block:: text
+
+    |       |WGP[0]|WGP[1]|WGP[2]|WGP[3]|
+    |-------|------|------|------|------|
+    | SH[0] |   1  |   2  |   3  |   4  |
+    | SH[1] |   5  |   6  |   7  |   8  |
+    | SH[2] |   9  |   10 |   11 |   12 |
+    | SH[3] |   13 |   14 |   15 |   16 |
+
+#### XCC[1]:
+
+.. code-block:: text
+
+    |       |WGP[0]|WGP[1]|WGP[2]|WGP[3]|
+    |-------|------|------|------|------|
+    | SH[0] |   1  |   2  |   3  |   4  |
+    | SH[1] |   5  |   6  |   7  |   8  |
+    | SH[2] |   9  |   10 |   11 |   12 |
+    | SH[3] |   13 |   14 |   15 |   16 |
+
+Reducing XCC dim with sum, results to 2D space with only WGP and SH.
+
+.. code-block:: text
+
+    |       |WGP[0]|WGP[1]|WGP[2]|WGP[3]|
+    |-------|------|------|------|------|
+    | SH[0] |  2   |   4  |   6  |   8  |
+    | SH[1] |  10  |   12 |   14 |   16 |
+    | SH[2] |  18  |   20 |   22 |   24 |
+    | SH[3] |  26  |   28 |   30 |   32 |
+
+similarly, for ``reduce(X,sum,[DIMENSION_XCC,DIMENSION_SHADER_ARRAY])`` results in only WGP dimension.
+
+.. code-block:: text
+
+    |       |WGP[0]|WGP[1]|WGP[2]|WGP[3]|
+    |-------|------|------|------|------|
+    |       |  56  |  64  |  72  |  80  |
+
+Select Function
+++++++++++++++++
+
+.. code-block:: yaml
+
+    expression: select(Y, [DIMENSION_XCC=[0],DIMENSION_SHADER_ENGINE=[2]])
+
+select() only returns counter values which match the dimension indexes provided by the user in expression. This operation is to allow a user to state they only want to select specific dimensions index. Supported dimensions include ``DIMENSION_XCC, DIMENSION_AID, DIMENSION_SHADER_ENGINE, DIMENSION_AGENT, DIMENSION_SHADER_ARRAY, DIMENSION_WGP, DIMENSION_INSTANCE``. For example ``select(Y, [DIMENSION_XCC=[0],DIMENSION_SHADER_ENGINE=[2]])`` gives counter values which are from DIMENSION_XCC= 0 and DIMENSION_SHADER_ENGINE= 2 for Y Metric.
+
+Let's say Y has XCC, SHADER_ENGINE (SE), WGP dimensions with sizes 2, 4, 4 respectively.
+
+Raw Counter Data in 3D space:
+
+#### XCC[0]:
+
+.. code-block:: text
+
+    |       |WGP[0]|WGP[1]|WGP[2]|WGP[3]|
+    |-------|------|------|------|------|
+    | SE[0] |   1  |   2  |   3  |   4  |
+    | SE[1] |   5  |   6  |   7  |   8  |
+    | SE[2] |   9  |   10 |   11 |   12 |
+    | SE[3] |   13 |   14 |   15 |   16 |
+
+#### XCC[1]:
+
+.. code-block:: text
+
+    |       |WGP[0]|WGP[1]|WGP[2]|WGP[3]|
+    |-------|------|------|------|------|
+    | SE[0] |   17 |   18 |   19 |   20 |
+    | SE[1] |   21 |   22 |   23 |   24 |
+    | SE[2] |   25 |   26 |   27 |   28 |
+    | SE[3] |   29 |   30 |   31 |   32 |
+
+Selecting at XCC=0 results to 2D space with WGP and SH dimensions, as shown below.
+
+.. code-block:: text
+
+    |       |WGP[0]|WGP[1]|WGP[2]|WGP[3]|
+    |-------|------|------|------|------|
+    | SE[0] |   1  |   2  |   3  |   4  |
+    | SE[1] |   5  |   6  |   7  |   8  |
+    | SE[2] |   9  |   10 |   11 |   12 |
+    | SE[3] |   13 |   14 |   15 |   16 |
+
+similarly, for ``select(Y, [DIMENSION_XCC=[0],DIMENSION_SHADER_ENGINE=[2]])`` results in only WGP dimension with XCC=0 and SE=2.
+
+.. code-block:: text
+
+    |       |WGP[0]|WGP[1]|WGP[2]|WGP[3]|
+    |-------|------|------|------|------|
+    |       |  9   |  10  |  11  |  12  |
+
+Accumulate Function
+-------------------
+
+.. code-block:: yaml
+
+    Expression: accumulate(<basic_level_counter>, <resolution>)
+
+- The accumulate function sums the values of a basic level counter over the specified number of cycles. The ``resolution`` parameter allows you to control the frequency of the following summing operation:
+
+  - ``HIGH_RES``: Sums up the basic level counter every clock cycle. Captures the value every cycle for higher accuracy, which helps in fine-grained analysis.
+  - ``LOW_RES``: Sums up the basic level counter every four clock cycles. Reduces the data points and provides less detailed summing, which helps in reducing data volume.
+  - ``NONE``: Does nothing and is equivalent to collecting basic level counter. Outputs the value of the basic level counter without performing any summing operation.
+
+**Example:**
+
+.. code-block:: yaml
+
+    MeanOccupancyPerCU:
+      architectures:
+        gfx942/gfx941/gfx940:
+          expression: accumulate(SQ_LEVEL_WAVES,HIGH_RES)/reduce(GRBM_GUI_ACTIVE,max)/CU_NUM
+      description: Mean occupancy per compute unit.
+
+<metric name="MeanOccupancyPerCU" expr=accumulate(SQ_LEVEL_WAVES,HIGH_RES)/reduce(GRBM_GUI_ACTIVE,max)/CU_NUM descr="Mean occupancy per compute unit."></metric>
+
+- ``MeanOccupancyPerCU``: In the preceding example, the ``MeanOccupancyPerCU`` metric calculates the mean occupancy per compute unit. It uses the accumulate function with ``HIGH_RES`` to sum the ``SQ_LEVEL_WAVES`` counter every clock cycle. This sum is then divided by the maximum value of GRBM_GUI_ACTIVE and the number of compute units ``CU_NUM`` to derive the mean occupancy.
+
+Kernel Serialization
+--------------------
+
+Counter collection in *dispatch counting* mode requires serialized execution of kernels on a target device. Kernel serialization isolates kernel executions, which helps to collect performance counter data. However, for applications requiring two kernels to execute on the same device simultaneously (co-dependent kernels), kernel serialization leads to deadlock in dispatch counter collection mode. To avoid deadlock in such applications, opt for any of the following options:
+
+- Avoid co-dependent kernels in application.
+
+- Don't collect performance data for co-dependent kernels by using kernel filtration methods in the rocprofv3’s input configuration PMC file.
+
+- Use ROCprofiler-SDK's device-wide counter collection mode to collect performance data. You can use tools such as RDC and PAPI to collect information. Note that the device-wide counter collection captures data for all executions on the device and not specific to the kernels.

projects/rocprofiler-sdk/source/docs/api-reference/intercept_table.rst

@@ -0,0 +1,99 @@
+
+.. meta::
+    :description: ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software
+    :keywords: ROCprofiler-SDK API reference, ROCprofiler-SDK intercept table, Intercept table API
+
+.. _runtime-intercept-tables:
+
+Runtime intercept tables
+=========================
+
+While tools commonly leverage the callback or buffer tracing services for tracing the HIP, HSA, and ROCTx
+APIs, ROCprofiler-SDK also provides access to the raw API dispatch tables.
+
+Forward declaration of public C API function
+----------------------------------------------
+
+All the aforementioned APIs are designed similar to the following sample:
+
+.. code-block:: cpp
+
+    extern "C"
+    {
+    // forward declaration of public C API function
+    int
+    foo(int) __attribute__((visibility("default")));
+    }
+
+Internal implementation of API function
+-----------------------------------------
+
+.. code-block:: cpp
+
+    namespace impl
+    {
+    int
+    foo(int val)
+    {
+        // real implementation
+        return (2 * val);
+    }
+    }
+
+Dispatch table implementation
+-------------------------------
+
+.. code-block:: cpp
+
+    namespace impl
+    {
+    struct dispatch_table
+    {
+        int (*foo_fn)(int) = nullptr;
+    };
+
+    // Invoked once: populates the dispatch_table with function pointers to implementation
+    dispatch_table*&
+    construct_dispatch_table()
+    {
+        static dispatch_table* tbl = new dispatch_table{};
+        tbl->foo_fn                = impl::foo;
+
+        // In between, ROCprofiler-SDK gets passed the pointer
+        // to the dispatch table and has the opportunity to wrap the function
+        // pointers for interception
+
+        return tbl;
+    }
+
+    // Constructs dispatch table and stores it in static variable
+    dispatch_table*
+    get_dispatch_table()
+    {
+        static dispatch_table*& tbl = construct_dispatch_table();
+        return tbl;
+    }
+    }  // namespace impl
+
+Implementation of public C API function
+-----------------------------------------
+
+.. code-block:: cpp
+
+    extern "C"
+    {
+    // implementation of public C API function
+    int
+    foo(int val)
+    {
+        return impl::get_dispatch_table()->foo_fn(val);
+    }
+    }
+
+Dispatch table chaining
+-------------------------
+
+ROCprofiler-SDK can save the original values of the function pointers such as ``foo_fn`` in ``impl::construct_dispatch_table()`` and install its own function pointers in its place. This results in the public C API function ``foo`` calling into the ROCprofiler-SDK function pointer, which in turn, calls the original function pointer to ``impl::foo``. This phenomenon is named chaining. Once ROCprofiler-SDK
+makes necessary modifications to the dispatch table, tools requesting access to the raw dispatch table via ``rocprofiler_at_intercept_table_registration`` are provided the pointer to the dispatch table.
+
+For examples on dispatch table chaining, see `samples/intercept_table <https://github.com/ROCm/rocprofiler-sdk/tree/amd-staging/samples/intercept_table>`_.

projects/rocprofiler-sdk/source/docs/api-reference/pc_sampling.rst

@@ -0,0 +1,179 @@
+
+.. meta::
+    :description: ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software
+    :keywords: ROCprofiler-SDK API reference, Program counter sampling, PC sampling
+
+.. _pc-sampling:
+
+ROCprofiler-SDK PC sampling method
+===================================
+
+Program Counter (PC) sampling is a profiling method that uses statistical approximation of the kernel execution by sampling GPU program counters. Furthermore, this method periodically chooses an active wave in a round robin manner and snapshots its PC. This process takes place on every compute unit simultaneously, making it device-wide PC sampling. The outcome is the histogram of samples, explaining how many times each kernel instruction was sampled.
+
+.. warning::
+
+    Risk acknowledgment: The PC sampling feature is under development and might not be completely stable. Use this beta feature cautiously. It may affect your system's stability and performance. Proceed at your own risk.
+
+    By activating this feature through ``ROCPROFILER_PC_SAMPLING_BETA_ENABLED`` environment variable, you acknowledge and accept the following potential risks:
+
+    - Hardware freeze: This beta feature could cause your hardware to freeze unexpectedly.
+    - Need for cold restart: In the event of a hardware freeze, you might need to perform a cold restart (turning the hardware off and on) to restore normal operations.
+
+ROCprofiler-SDK PC sampling service
+------------------------------------
+
+This section describes how to use ROCProfiler-SDK PC sampling API to configure and use PC sampling service. For fully functional examples, see `Samples <https://github.com/ROCm/rocprofiler-sdk/tree/amd-mainline/samples>`_.
+
+tool_init() setup
+++++++++++++++++++
+
+Here are the steps to set up ``tool_init()``:
+
+.. code-block:: cpp
+
+    rocprofiler_context_id_t ctx{0};
+    rocprofiler_buffer_id_t buff;
+    ROCPROFILER_CALL(rocprofiler_create_context(&ctx), "context creation failed");
+    ROCPROFILER_CALL(rocprofiler_create_buffer(ctx,
+                                                8192,
+                                                2048,
+                                                ROCPROFILER_BUFFER_POLICY_LOSSLESS,
+                                                pc_sampling_callback, // Callback to process PC samples
+                                                user_data,
+                                                &buff),
+                        "buffer creation failed");
+
+For more details on buffer creation, see :ref:`buffered-services`.
+
+The PC sampling service is tied to a GPU agent. To extract the list of available agents, use the ``rocprofiler_query_available_agents`` as shown in the following code snippet:
+
+.. code-block:: cpp
+
+    std::vector<rocprofiler_agent_v0_t> agents;
+
+    // Callback used by rocprofiler_query_available_agents to return
+    // agents on the device. This can include CPU agents as well.
+    // Select GPU agents only (type == ROCPROFILER_AGENT_TYPE_GPU)
+    rocprofiler_query_available_agents_cb_t iterate_cb = [](rocprofiler_agent_version_t agents_ver,
+                                                            const void**                agents_arr,
+                                                            size_t                      num_agents,
+                                                            void*                       udata) {
+        if(agents_ver != ROCPROFILER_AGENT_INFO_VERSION_0)
+            throw std::runtime_error{"unexpected rocprofiler agent version"};
+        auto* agents_v = static_cast<std::vector<rocprofiler_agent_v0_t>*>(udata);
+        for(size_t i = 0; i < num_agents; ++i)
+        {
+            const auto* agent = static_cast<const rocprofiler_agent_v0_t*>(agents_arr[i]);
+            if(agent->type == ROCPROFILER_AGENT_TYPE_GPU) agents_v->emplace_back(*agent);
+        }
+        return ROCPROFILER_STATUS_SUCCESS;
+    };
+
+    // Query the agents. Only a single callback is made that contains a vector
+    // of all agents.
+    ROCPROFILER_CALL(
+        rocprofiler_query_available_agents(ROCPROFILER_AGENT_INFO_VERSION_0,
+                                           iterate_cb,
+                                           sizeof(rocprofiler_agent_t),
+                                           const_cast<void*>(static_cast<const void*>(&agents))),
+        "query available agents");
+
+Only newer GPU architectures (MI200 onwards) support this feature. To determine whether an agent with ``agent_id`` supports the PC sampling and the available configurations ``(rocprofiler_pc_sampling_configuration_t)``, use the `rocprofiler_query_pc_sampling_agent_configurations`.
+
+.. code-block:: cpp
+
+    std::vector<rocprofiler_pc_sampling_configuration_t> available_configurations;
+
+    auto cb = [](const rocprofiler_pc_sampling_configuration_t* configs,
+                 size_t                                         num_config,
+                 void*                                          user_data) {
+        auto* avail_configs = static_cast<avail_configs_vec_t*>(user_data);
+        for(size_t i = 0; i < num_config; i++)
+        {
+            avail_configs->emplace_back(configs[i]);
+        }
+        return ROCPROFILER_STATUS_SUCCESS;
+    };
+
+    auto status = rocprofiler_query_pc_sampling_agent_configurations(
+        agent_id, cb, &available_configurations);
+
+Assuming the `available_configurations` contain a single element:
+
+.. code-block:: cpp
+
+    rocprofiler_pc_sampling_configuration_t {
+        .method = ROCPROFILER_PC_SAMPLING_METHOD_HOST_TRAP,
+        .unit = ROCPROFILER_PC_SAMPLING_UNIT_TIME,
+        .min_interval = 1,
+        .max_interval = 10000
+    };
+
+
+Configure the PC sampling service on an agent with ``agent_id`` to generate samples every 1000 micro-seconds as shown here:
+
+.. code-block:: cpp
+
+    auto status = rocprofiler_configure_pc_sampling_service(ctx,
+                                                            agent_id,
+                                                            picked_cfg->method,
+                                                            picked_cfg->unit,
+                                                            1000,  // 1000 us
+                                                            buffer_id,
+                                                            0);
+    if (status == ROCPROFILER_STATUS_SUCCESS)
+    {
+        // PC Sampling service has been configured successfully.
+    }
+    else
+    {
+        // code for error handling
+    }
+
+.. note::
+
+    Multiple processes can share the same GPU agent simultaneously, so the following A->B->A problem is possible on shared systems. For example, process A can query available configurations and opt to configure the service with configuration CA. However, if process B manages to finish configuring the service with configuration CB, then process A will fail. Thus, it is advisable for process A to repeat the querying process to observe configuration CB and reuse it for configuring the PC sampling service. For more details, refer to the `Samples <https://github.com/ROCm/rocprofiler-sdk/tree/amd-mainline/samples>`_.
+
+Processing PC samples
+----------------------
+
+The PC sampling service asynchronously delivers samples via a dedicated callback ``(pc_sampling_callback)``. The following code snippet outlines the process of iterating over samples.
+
+.. code-block:: cpp
+
+    void
+    pc_sampling_callback(rocprofiler_context_id_t ctx,
+                         rocprofiler_buffer_id_t buff,
+                         rocprofiler_record_header_t** headers,
+                         size_t num_headers,
+                         void* data,
+                         uint64_t drop_count)
+    {
+        for(size_t i = 0; i < num_headers; i++)
+        {
+            auto* cur_header = headers[i];
+
+            if(cur_header->category == ROCPROFILER_BUFFER_CATEGORY_PC_SAMPLING)
+            {
+                if(cur_header->kind == ROCPROFILER_PC_SAMPLING_RECORD_HOST_TRAP_V0_SAMPLE)
+                {
+                    auto* pc_sample = static_cast<rocprofiler_pc_sampling_record_host_trap_v0_t*>(
+                        cur_header->payload);
+
+                    // Processing a single sample...
+                }
+                else
+                {
+                    // ...
+                }
+            }
+        }
+    }
+
+For more information on the data comprising a single sample, see `pc_sampling.h <https://github.com/ROCm/rocprofiler-sdk/blob/amd-mainline/source/include/rocprofiler-sdk/pc_sampling.h>`_.
+
+.. note::
+    A user can synchronously flush buffers via ``rocprofiler_buffer_flush`` that triggers ``pc_sampling_callback``.
+
+
+

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk-roctx_api/global_roctx_data_structures_topics_files.rst

@@ -0,0 +1,15 @@
+.. meta::
+  :description: The Global Data structures, topics and files reference page.
+
+.. _global_roctx_data_structures_topics_files_reference:
+
+*******************************************************************************
+Global Data structures, topics, files
+*******************************************************************************
+
+This ROCprofiler-SDK-ROCTx API topic covers:
+
+* :ref:`global_roctx_basic_data_types_reference`
+* :doc:`../../_doxygen/roctx/html/topics`
+* :doc:`../../_doxygen/roctx/html/files`
+

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk-roctx_api/global_roctx_data_structures_topics_files/global_roctx_basic_data_types.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The global basic data types reference page.
+
+.. _global_roctx_basic_data_types_reference:
+
+*******************************************************************************
+Global Basic Data Types
+*******************************************************************************
+
+.. doxygengroup:: BASIC_DATA_TYPES
+   :content-only:
+   :project: roctx

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk-roctx_api/roctx_modules.rst

@@ -0,0 +1,17 @@
+.. meta::
+  :description: The ROCprofiler-SDK-ROCTx API modules reference page.
+  :keywords: AMD, ROCm, modules
+
+.. _roctx_modules_reference:
+
+*******************************************************************************
+Modules
+*******************************************************************************
+
+The ROCprofiler-SDK-ROCTx API is organized into the following modules based on functionality:
+
+* :ref:`markers_information_reference`
+* :ref:`ranges_information_reference`
+* :ref:`profiler-control_information_reference`
+* :ref:`naming-utilities_information_reference`
+

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk-roctx_api/roctx_modules/markers.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: Markers Information reference page.
+
+.. _markers_information_reference:
+
+*******************************************************************************
+Markers Information
+*******************************************************************************
+
+.. doxygengroup:: marker_group
+   :content-only:
+   :project: roctx

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk-roctx_api/roctx_modules/naming-utilities.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: Naming utilities Information reference page.
+
+.. _naming-utilities_information_reference:
+
+*******************************************************************************
+Naming Information
+*******************************************************************************
+
+.. doxygengroup:: UTILITIES
+   :content-only:
+   :project: roctx

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk-roctx_api/roctx_modules/profiler-control.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: Profiler Control Information reference page.
+
+.. _profiler-control_information_reference:
+
+*******************************************************************************
+Profiler Control Information
+*******************************************************************************
+
+.. doxygengroup:: PROFILER_COMM
+   :content-only:
+   :project: roctx

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk-roctx_api/roctx_modules/ranges.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: Ranges Information reference page.
+
+.. _ranges_information_reference:
+
+*******************************************************************************
+Ranges Information
+*******************************************************************************
+
+.. doxygengroup:: range_group
+   :content-only:
+   :project: roctx

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk-roctx_api_reference.rst

@@ -0,0 +1,66 @@
+.. meta::
+  :description: ROCprofiler-SDK-ROCTx API reference page
+  :keywords: AMD, ROCm, HSA
+
+.. _rocprofiler_sdk_roctx_api_reference:
+
+********************************************************************************
+ROCTx API
+********************************************************************************
+
+Introduction
+============
+
+ROCTx is a comprehensive library that implements the AMD code annotation API. It provides
+essential functionality for:
+
+- Event annotation and marking
+- Code range tracking and management
+- Profiler control and customization
+- Thread and device naming capabilities
+
+Key features:
+
+- Nested range tracking with push/pop functionality
+- Process-wide range management
+- Thread-specific and global profiler control
+- Device and stream naming support
+- HSA agent and HIP device management
+
+The API is divided into several main components:
+
+1. **Markers** - For single event annotations
+2. **Ranges** - For tracking code execution spans
+3. **Profiler Control** - For managing profiling tool behavior
+4. **Naming Utilities** - For labeling threads, devices, and streams
+
+Thread Safety:
+
+- Range operations are thread-local and thread-safe
+- Marking operations are thread-safe
+- Profiler control operations are process-wide
+
+Integration:
+
+- Compatible with HIP runtime
+- Supports HSA (Heterogeneous System Architecture)
+- Provides both C and C++ interfaces
+
+Performance Considerations:
+
+- Minimal overhead for marking and range operations
+- Thread-local storage for efficient range stacking
+- Lightweight profiler control mechanisms
+
+.. note::
+
+   All string parameters must be null-terminated.
+
+.. warning::
+
+   Proper nesting of range push/pop operations is the user's responsibility.
+
+This ROCTx API topic broadly covers:
+
+* :ref:`roctx_modules_reference`
+* :ref:`global_roctx_data_structures_topics_files_reference`

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/global_data_structures_topics_files.rst

@@ -0,0 +1,15 @@
+.. meta::
+  :description: The Global Data structures, topics and files reference page.
+
+.. _global_data_structures_topics_files_reference:
+
+*******************************************************************************
+Global Data structures, topics, files
+*******************************************************************************
+
+This ROCprofiler-SDK API topic covers:
+
+* :ref:`global_basic_data_types_reference`
+* :doc:`../../_doxygen/rocprofiler-sdk/html/topics`
+* :doc:`../../_doxygen/rocprofiler-sdk/html/annotated`
+* :doc:`../../_doxygen/rocprofiler-sdk/html/files`

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/global_data_structures_topics_files/global_basic_data_types.rst

@@ -0,0 +1,11 @@
+.. meta::
+  :description: The global basic data types reference page.
+
+.. _global_basic_data_types_reference:
+
+*******************************************************************************
+Global Basic Data Types
+*******************************************************************************
+
+.. doxygengroup:: BASIC_DATA_TYPES
+   :content-only:

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules.rst

@@ -0,0 +1,28 @@
+.. meta::
+  :description: The ROCprofiler-SDK API modules reference page.
+  :keywords: AMD, ROCm, modules
+
+.. _modules_reference:
+
+*******************************************************************************
+Modules
+*******************************************************************************
+
+The ROCprofiler-SDK API is organized into the following modules based on functionality:
+
+* :ref:`agent_information_reference`
+* :ref:`buffer_handling_reference`
+* :ref:`buffer_tracing_reference`
+* :ref:`callback_tracing_reference`
+* :ref:`context_management_reference`
+* :ref:`counters_reference`
+* :ref:`counter_config_reference`
+* :ref:`device_counting_service_reference`
+* :ref:`dispatch_counting_service_reference`
+* :ref:`external_correlation_reference`
+* :ref:`intercept_table_reference`
+* :ref:`internal_threading_management_reference`
+* :ref:`ompt_registration_reference`
+* :ref:`pc_sampling_service_reference`
+* :ref:`thread_trace_reference`
+* :ref:`tool_registration_reference`

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/agent_information.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The Agent Information reference page.
+
+.. _agent_information_reference:
+
+*******************************************************************************
+Agent Information
+*******************************************************************************
+
+.. doxygengroup:: AGENTS
+   :project: rocprofiler-sdk
+   :content-only:

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/buffer_handling.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The buffer handling reference page.
+
+.. _buffer_handling_reference:
+
+*******************************************************************************
+Buffer handling
+*******************************************************************************
+
+.. doxygengroup:: BUFFER_HANDLING
+   :content-only:
+   :project: rocprofiler-sdk

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/buffer_tracing.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The buffer tracing reference page.
+
+.. _buffer_tracing_reference:
+
+*******************************************************************************
+Buffer tracing
+*******************************************************************************
+
+.. doxygengroup:: BUFFER_TRACING_SERVICE
+   :content-only:
+   :project: rocprofiler-sdk

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/callback_tracing.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The callback tracing reference page.
+
+.. _callback_tracing_reference:
+
+*******************************************************************************
+Callback tracing
+*******************************************************************************
+
+.. doxygengroup:: CALLBACK_TRACING_SERVICE
+   :content-only:
+   :project: rocprofiler-sdk   

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/context_management.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The context management reference page.
+
+.. _context_management_reference:
+
+*******************************************************************************
+Context management
+*******************************************************************************
+
+.. doxygengroup:: CONTEXT_OPERATIONS
+   :content-only:
+   :project: rocprofiler-sdk

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/counter_config.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The counter config reference page.
+
+.. _counter_config_reference:
+
+*******************************************************************************
+Counter config
+*******************************************************************************
+
+.. doxygengroup:: COUNTER_CONFIG
+   :content-only:
+   :project: rocprofiler-sdk

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/counters.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The counters reference page.
+
+.. _counters_reference:
+
+*******************************************************************************
+Counters
+*******************************************************************************
+
+.. doxygengroup:: COUNTERS
+   :content-only:
+   :project: rocprofiler-sdk   

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/device_counting_service.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The device counting service reference page.
+
+.. _device_counting_service_reference:
+
+*******************************************************************************
+Device counting service
+*******************************************************************************
+
+.. doxygengroup:: device_counting_service
+   :content-only:
+   :project: rocprofiler-sdk

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/dispatch_counting_service.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The dispatch counting service reference page.
+
+.. _dispatch_counting_service_reference:
+
+*******************************************************************************
+Dispatch counting service
+*******************************************************************************
+
+.. doxygengroup:: dispatch_counting_service
+   :content-only:
+   :project: rocprofiler-sdk

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/external_correalation.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The external correlation reference page.
+
+.. _external_correlation_reference:
+
+*******************************************************************************
+External correlation
+*******************************************************************************
+
+.. doxygengroup:: EXTERNAL_CORRELATION
+   :content-only:
+   :project: rocprofiler-sdk

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/intercept_table.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The Intercept table reference page.
+
+.. _intercept_table_reference:
+
+*******************************************************************************
+Intercept table
+*******************************************************************************
+
+.. doxygengroup:: INTERCEPT_TABLE
+   :content-only:
+   :project: rocprofiler-sdk

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/internal_threading_management.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The intenal threading management reference page.
+
+.. _internal_threading_management_reference:
+
+*******************************************************************************
+Internal threading management
+*******************************************************************************
+
+.. doxygengroup:: INTERNAL_THREADING
+   :content-only:
+   :project: rocprofiler-sdk

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/ompt_registration.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The OMPT Registration reference page.
+
+.. _ompt_registration_reference:
+
+*******************************************************************************
+OMPT Registration
+*******************************************************************************
+
+.. doxygengroup:: OMPT_REGISTRATION
+   :content-only:
+   :project: rocprofiler-sdk

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/pc_sampling_service.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The PC Sampling service reference page.
+
+.. _pc_sampling_service_reference:
+
+*******************************************************************************
+PC Sampling service
+*******************************************************************************
+
+.. doxygengroup:: PC_SAMPLING_SERVICE
+   :content-only:
+   :project: rocprofiler-sdk

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/thread_trace.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The thread trace reference page.
+
+.. _thread_trace_reference:
+
+*******************************************************************************
+Thread trace
+*******************************************************************************
+
+.. doxygengroup:: THREAD_TRACE
+   :content-only:
+   :project: rocprofiler-sdk

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api/modules/tool_registration.rst

@@ -0,0 +1,12 @@
+.. meta::
+  :description: The tool registration reference page.
+
+.. _tool_registration_reference:
+
+*******************************************************************************
+Tool registration
+*******************************************************************************
+
+.. doxygengroup:: REGISTRATION_GROUP
+   :content-only:
+   :project: rocprofiler-sdk

projects/rocprofiler-sdk/source/docs/api-reference/rocprofiler-sdk_api_reference.rst

@@ -0,0 +1,14 @@
+.. meta::
+  :description: ROCprofiler-SDK API reference page
+  :keywords: AMD, ROCm, HSA
+
+.. _rocprofiler_sdk_api_reference:
+
+********************************************************************************
+ROCprofiler-SDK API library
+********************************************************************************
+
+This ROCprofiler-SDK API topic covers:
+
+* :ref:`modules_reference`
+* :ref:`global_data_structures_topics_files_reference`

projects/rocprofiler-sdk/source/docs/api-reference/thread_trace.rst

@@ -0,0 +1,357 @@
+.. meta::
+    :description: ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software stack
+    :keywords: ROCprofiler-SDK API reference, Thread trace, ROCprof Trace Decoder, SQTT, ATT, GPU tracing
+
+.. _thread-trace:
+
+ROCprof Trace Decoder and thread trace APIs
+======================================================
+
+Thread trace is a profiling method that provides fine-grained insight into GPU kernel execution by collecting detailed traces of shader instructions executed by the GPU. This feature captures GPU occupancy, instruction execution times, fast performance counters, and other detailed performance data. Thread trace utilizes GPU hardware instrumentation to record events as they happen, resulting in precise timing information about wave (threads) execution behavior.
+
+ROCprofiler-SDK provides wrapper APIs for the ROCprof Trace Decoder, a library to decode thread trace data.
+
+.. note::
+
+    Thread trace can generate large amounts of data, especially when profiling complex applications or longer execution runs. This might require handling potentially high volumes of trace data, so it’s recommended to implement appropriate filtering strategies to focus on the specific parts of interest in your application.
+
+.. note::
+
+    ROCprof Trace Decoder is a binary-only library and can be found `here <https://github.com/ROCm/rocprof-trace-decoder/releases>`_.
+
+Thread trace service API
+------------------------------------
+
+This section describes how to use the ROCprofiler-SDK thread trace API to configure and use the thread trace service. For fully functional examples, see `Samples <https://github.com/ROCm/rocprofiler-sdk/tree/amd-mainline/samples/thread_trace>`_.
+
+tool_init() setup
+++++++++++++++++++
+
+Here are the steps to set up ``tool_init()`` for thread trace:
+
+1. Configure callback tracing for code objects to get disassembly information:
+
+
+.. code-block:: cpp
+
+    rocprofiler_context_id_t ctx{0};
+    ROCPROFILER_CALL(rocprofiler_create_context(&ctx), "context creation failed");
+
+    ROCPROFILER_CALL(
+        rocprofiler_configure_callback_tracing_service(ctx,
+                                                       ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT,
+                                                       nullptr,
+                                                       0,
+                                                       tool_codeobj_tracing_callback,
+                                                       nullptr),
+        "code object tracing service configure");
+
+2. The thread trace service is tied to a GPU agent. To extract the list of available agents, use the ``rocprofiler_query_available_agents`` function:
+
+.. code-block:: cpp
+
+    std::vector<rocprofiler_agent_id_t> agents{};
+
+    ROCPROFILER_CALL(
+        rocprofiler_query_available_agents(
+            ROCPROFILER_AGENT_INFO_VERSION_0,
+            [](rocprofiler_agent_version_t, const void** _agents, size_t _num_agents, void* _data) {
+                auto* agent_v = static_cast<std::vector<rocprofiler_agent_id_t>*>(_data);
+                for(size_t i = 0; i < _num_agents; ++i)
+                {
+                    auto* agent = static_cast<const rocprofiler_agent_v0_t*>(_agents[i]);
+                    if(agent->type == ROCPROFILER_AGENT_TYPE_GPU) 
+                        agent_v->emplace_back(agent->id);
+                }
+                return ROCPROFILER_STATUS_SUCCESS;
+            },
+            sizeof(rocprofiler_agent_v0_t),
+            &agents),
+        "Failed to iterate agents");
+
+3. Optionally, specify the configuration parameters:
+
+.. code-block:: cpp
+
+    std::vector<rocprofiler_thread_trace_parameter_t> params{};
+    
+    params.push_back({ROCPROFILER_THREAD_TRACE_PARAMETER_SHADER_ENGINE_MASK, 0xF});
+    
+    params.push_back({ROCPROFILER_THREAD_TRACE_PARAMETER_TARGET_CU, 0});
+    
+    params.push_back({ROCPROFILER_THREAD_TRACE_PARAMETER_SIMD_SELECT, 0xF});
+    
+    params.push_back({ROCPROFILER_THREAD_TRACE_PARAMETER_BUFFER_SIZE, 1u<<30}); // 1 GB
+    
+The configuration parameters are described here:
+
+- ROCPROFILER_THREAD_TRACE_PARAMETER_SHADER_ENGINE_MASK: Configures the Shader Engine (SE) mask, which determines the SEs to be traced. This is a bitmask where each bit corresponds to a SE. For MI3xx, each hex digit corresponds to an XCD. It's highly recommended to trace only one SE at a time to avoid data loss.
+
+- ROCPROFILER_THREAD_TRACE_PARAMETER_TARGET_CU: Configures the target Compute Unit (CU) or WGP. Instruction tracing can only operate on a single CU or WGP at a time. The same target is used for all SEs in ``ROCPROFILER_THREAD_TRACE_PARAMETER_SHADER_ENGINE_MASK``.
+  
+- ROCPROFILER_THREAD_TRACE_PARAMETER_SIMD_SELECT: Configures SIMD selection. For gfx9, this is a bitmask where each bit corresponds to a SIMD lane. For example, 0xF selects all SIMD lanes in the ``target_cu``. For gfx10, gfx11, and gfx12, this selects a single SIMD ID to trace. Results are taken mod4 for compatibility with gfx9 so 0xF selects SIMD3 of the target WGP.
+
+- ROCPROFILER_THREAD_TRACE_PARAMETER_BUFFER_SIZE: Configures the buffer size. This buffer is shared among all SEs specified in ROCPROFILER_THREAD_TRACE_PARAMETER_SHADER_ENGINE_MASK. There is a minimal side effect to specifying a larger buffer size, except for increased VRAM usage.
+
+
+The thread trace can be configured in two primary modes: device-wide or per-dispatch, as described in the following sections.
+
+Device thread trace
++++++++++++++++++++
+
+To enable thread trace service asynchronously or independently of kernel dispatches on a device, use:
+
+.. code-block:: cpp
+
+    // For device thread trace, it's recommended to create a separate context just to enable and disable the service independently.
+    for(auto agent_id : agents)
+    {
+        ROCPROFILER_CALL(
+            rocprofiler_configure_device_thread_trace_service(
+                ctx,
+                agent_id,
+                params.data(),
+                params.size(),
+                shader_data_callback,
+                nullptr),
+            "thread trace service configure");
+    }
+
+Dispatch thread trace
++++++++++++++++++++++
+
+To enable selective thread trace based on specific kernel dispatches, use the dispatch-based configuration. By default, only the traced kernels are serialized in dispatch tracing. An optional parameter is provided to serialize all kernels, which ensures no parallel kernel execution during tracing.
+
+.. code-block:: cpp
+
+    // (Optional) To serialize ALL kernels, not just the traced ones
+    // This ensures no parallel kernel execution during tracing
+    params.push_back({ROCPROFILER_THREAD_TRACE_PARAMETER_SERIALIZE_ALL, 1});
+
+    // Define dispatch callback to control thread trace
+    rocprofiler_thread_trace_control_flags_t
+    dispatch_callback(rocprofiler_agent_id_t agent_id,
+                      rocprofiler_queue_id_t queue_id,
+                      rocprofiler_async_correlation_id_t correlation_id,
+                      rocprofiler_kernel_id_t kernel_id,
+                      rocprofiler_dispatch_id_t dispatch_id,
+                      void* userdata,
+                      rocprofiler_user_data_t* dispatch_userdata)
+    {
+        // Trace only the desired kernels
+        if(target_kernel_id == kernel_id) 
+            return ROCPROFILER_THREAD_TRACE_CONTROL_START_AND_STOP;
+            
+        return ROCPROFILER_THREAD_TRACE_CONTROL_NONE;
+    }
+    
+    // Configure dispatch-based thread trace
+    for(auto agent_id : agents)
+    {
+        ROCPROFILER_CALL(
+            rocprofiler_configure_dispatch_thread_trace_service(
+                ctx,
+                agent_id,
+                params.data(),
+                params.size(),
+                dispatch_callback,
+                shader_data_callback,
+                nullptr),
+            "thread trace service configure");
+    }
+
+For device-wide thread trace, starting the context automatically begins data capture. Some application warmup is recommended before starting the device thread trace. For the dispatch thread trace, this step is not necessary as tracing doesn't start automatically.
+
+To start the context after all services are configured, use:
+
+.. code-block:: cpp
+
+    auto status = rocprofiler_start_context(ctx);
+
+    // Run your application workload here.
+    
+To stop the context to end data collection for device-wide thread trace, use:
+
+.. code-block:: cpp
+
+    status = rocprofiler_stop_context(ctx);
+
+ROCprof Trace Decoder API
+--------------------------------
+
+The thread trace functionality requires you to install the ROCprof Trace Decoder package separately. This package provides the necessary decoder library for processing thread trace data. Ensure to install this package on your system before using the thread trace feature.
+
+Trace Decoder setup
+++++++++++++++
+
+To decode the raw thread trace data, create and initialize a Trace Decoder:
+
+.. code-block:: cpp
+
+    rocprofiler_thread_trace_decoder_handle_t decoder{};
+    
+    // Create the Trace Decoder with the path to the decoder library
+    ROCPROFILER_CALL(
+        rocprofiler_thread_trace_decoder_create(&decoder, "/opt/rocm/lib"),
+        "thread trace decoder creation");
+
+    // Adds code object load information, reported by the code object tracing service
+    ROCPROFILER_CALL(rocprofiler_thread_trace_decoder_codeobj_load(decoder,
+                                                                   code_object_id,
+                                                                   load_delta,
+                                                                   load_size,
+                                                                   data,
+                                                                   datasize),
+                    "code object load");
+
+Code object tracking
+++++++++++++++++++++
+
+To properly decode instruction addresses, track the code object information:
+
+.. code-block:: cpp
+
+    void
+    tool_codeobj_tracing_callback(rocprofiler_callback_tracing_record_t record,
+                                  rocprofiler_user_data_t* /* user_data */,
+                                  void* /* userdata */)
+    {
+        if(record.kind != ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT ||
+           record.operation != ROCPROFILER_CODE_OBJECT_LOAD)
+            return;
+
+        // Optionally, ROCPROFILER_CALLBACK_PHASE_UNLOAD can be handled by calling
+        // rocprofiler_thread_trace_decoder_codeobj_unload(decoder, data->code_object_id);
+        if(record.phase != ROCPROFILER_CALLBACK_PHASE_LOAD) return;
+
+        auto* data = static_cast<rocprofiler_callback_tracing_code_object_load_data_t*>(record.payload);
+        // TODO: Handle file storage types
+        if(data->storage_type == ROCPROFILER_CODE_OBJECT_STORAGE_TYPE_FILE) return;
+
+        auto* memorybase = reinterpret_cast<const void*>(data->memory_base);
+        
+        // Register code object with Trace Decoder
+        ROCPROFILER_CALL(
+            rocprofiler_thread_trace_decoder_codeobj_load(
+                decoder,
+                data->code_object_id,
+                data->load_delta,
+                data->load_size,
+                memorybase,
+                data->memory_size),
+            "code object loading to decoder");
+    }
+
+Processing thread trace data
+----------------------------
+
+.. note::
+
+    In the provided samples, thread trace data is processed immediately within the shader data callbacks for simplicity. In practice, it's recommended to save the data to a file or buffer and process it after the application completes. The rate at which thread trace generates data tends to be higher (GB/s) than the rate at which it can be processed (MB/s). Deferred processing is strongly recommended to avoid performance bottlenecks.
+
+The thread trace service asynchronously delivers raw trace data via a dedicated callback ``shader_data_callback``. This data must be processed using the Trace Decoder to generate useful information:
+
+.. code-block:: cpp
+
+    void
+    shader_data_callback(rocprofiler_agent_id_t agent,
+                         int64_t shader_engine_id,
+                         void* data,
+                         size_t data_size,
+                         rocprofiler_user_data_t userdata)
+    {
+        // Process shader callback data using the Trace Decoder.
+        auto status = rocprofiler_trace_decode(decoder_handle,
+                                               trace_decoder_callback,
+                                               data,
+                                               data_size,
+                                               userdata);
+    }
+
+Decoder callback
+++++++++++++++++
+
+The trace decoder provides decoded information through a callback:
+
+.. code-block:: cpp
+
+    // Callback for decoded thread trace data
+    void
+    trace_decoder_callback(rocprofiler_thread_trace_decoder_record_type_t record_type,
+                           void* trace_events,
+                           uint64_t trace_size,
+                           void* userdata)
+    {
+        switch(record_type)
+        {
+            case ROCPROFILER_THREAD_TRACE_DECODER_RECORD_WAVE:
+            {
+                // Process wave information
+                auto* waves = static_cast<rocprofiler_thread_trace_decoder_wave_t*>(trace_events);
+                for(uint64_t i = 0; i < trace_size; ++i)
+                {
+                    // Process wave data (timeline, instruction execution, etc.)
+                }
+                break;
+            }
+            
+            // Handle other record types as needed
+        }
+    }
+
+Trace Decoder info events
+++++++++++++++++++
+
+The Trace Decoder provides important information about the quality and comprehensiveness of the trace data through ``ROCPROFILER_THREAD_TRACE_DECODER_RECORD_INFO`` events. It is important to handle these events to understand potential issues with your trace data:
+
+- ROCPROFILER_THREAD_TRACE_DECODER_INFO_DATA_LOST
+
+  This event indicates that part of the trace data was dropped either due to hardware bandwidth limitations or buffer overflows. Receiving this event implies that portions of your trace might be missing or unreliable, which can affect the accuracy of any analysis based on the trace data.
+   
+  **Possible causes:**
+
+  - The trace buffer size was too small for the workload
+
+  - Memory bandwidth was exceeded
+   
+  **Recommended actions:**
+
+  - Increase buffer sizes if possible
+
+  - Reduce the number of SEs or SIMD lanes being traced
+
+  - Disable ``ROCPROFILER_THREAD_TRACE_PARAMETER_PERFCOUNTER`` or increase ``ROCPROFILER_THREAD_TRACE_PARAMETER_PERFCOUNTERS_CTRL`` if enabled
+
+
+
+- ROCPROFILER_THREAD_TRACE_DECODER_INFO_STITCH_INCOMPLETE
+
+  This event indicates that the Trace Decoder was unable to find the PC (Program Counter) address for one or more  traced instructions. Affected instructions will have their "pc" field set to zero.
+   
+  **Possible causes:**
+
+  - The trace was started in the middle of a kernel execution:
+
+    - If the trace was started after the kernel execution began, the Trace Decoder might not have received the necessary context to find the PC for all instructions.
+
+    - Subsequent dispatches function normally.
+
+  - Missing code object registration
+
+  - Runtime kernels present in the trace: These are not always reported in the code object tracing callbacks
+
+  - The ``ROCPROFILER_THREAD_TRACE_DECODER_INFO_DATA_LOST`` event was triggered. If parts of the trace were missing, important information might not have been available to the decoder.
+
+  - There is a possible bug in the Trace Decoder. If you suspect this, report it to the ROCprofiler team.
+
+For more information about the data structures and functions available for thread trace decoding, see the following headers:
+
+- `trace_decoder.h <https://github.com/ROCm/rocprofiler-sdk/blob/amd-mainline/source/include/rocprofiler-sdk/experimental/thread-trace/trace_decoder.h>`_
+
+- `trace_decoder_types.h <https://github.com/ROCm/rocprofiler-sdk/blob/amd-mainline/source/include/rocprofiler-sdk/experimental/thread-trace/trace_decoder_types.h>`_
+
+- `core.h <https://github.com/ROCm/rocprofiler-sdk/blob/amd-mainline/source/include/rocprofiler-sdk/experimental/thread-trace/core.h>`_
+
+- `dispatch.h <https://github.com/ROCm/rocprofiler-sdk/blob/amd-mainline/source/include/rocprofiler-sdk/experimental/thread-trace/dispatch.h>`_
+
+- `agent.h <https://github.com/ROCm/rocprofiler-sdk/blob/amd-mainline/source/include/rocprofiler-sdk/experimental/thread-trace/agent.h>`_

projects/rocprofiler-sdk/source/docs/api-reference/tool_library.rst

@@ -0,0 +1,239 @@
+
+.. meta::
+    :description: ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software
+    :keywords: ROCprofiler-SDK API reference, Tool library API
+
+.. _tool-library:
+
+ROCprofiler-SDK tool library
+============================
+
+The tool library utilizes APIs from ``rocprofiler-sdk`` and ``rocprofiler-register`` libraries for profiling and tracing HIP applications. This document provides information to help you design a tool by utilizing the ``rocprofiler-sdk`` and ``rocprofiler-register`` libraries efficiently. The command-line tool ``rocprofv3`` is also built on ``librocprofiler-sdk-tool.so.X.Y.Z``, which uses these libraries.
+
+ROCm runtimes design
+---------------------
+
+The ROCm runtimes are designed to directly communicate with a helper library named ``rocprofiler-register`` during initialization. This library performs cursory checks to find if a tool requires ROCprofiler-SDK services. This detection is based on the presence of one or more instances of ``rocprofiler_configure`` in the tool or ``ROCP_TOOL_LIBRARIES`` environment variable. This design provides drastic improvement over previous designs, which relied solely on a tool racing to set runtime-specific environment variables like ``HSA_TOOLS_LIB`` before the runtime initialization.
+
+Tool library design
+--------------------
+
+When ROCprofiler-SDK detects ``rocprofiler_configure`` in a tool's symbol table, ROCprofiler-SDK invokes ``rocprofiler_configure`` with parameters such as ROCprofiler-SDK version that invokes the function, number of tools already invoked, and a unique identifier for the tool. The tool returns a pointer to a ``rocprofiler_tool_configure_result_t`` struct, which, if non-null, provides ROCprofiler-SDK with:
+
+- Function to be called for tool initialization, which is also the opportunity for context creation.
+- Function to be called when ROCprofiler-SDK is finalized.
+- A pointer to data to be provided to the tool when ROCprofiler-SDK calls the initialization and finalization functions.
+
+ROCprofiler-SDK provides a ``rocprofiler-sdk/registration.h`` header file, which forward declares the ``rocprofiler_configure`` function with the necessary compiler function attributes to ensure that the ``rocprofiler_configure`` symbol is publicly visible.
+
+.. code-block:: cpp
+
+    #include <rocprofiler-sdk/registration.h>
+
+    namespace
+    {
+    struct ToolData
+    {
+        uint32_t                              version;
+        const char*                           runtime_version;
+        uint32_t                              priority;
+        rocprofiler_client_id_t               client_id;
+    };
+
+    int
+    tool_init(rocprofiler_client_finalize_t fini_func,
+              void* tool_data_v);
+
+    void
+    tool_fini(void* tool_data_v);
+    }
+
+    extern "C"
+    {
+    rocprofiler_tool_configure_result_t*
+    rocprofiler_configure(uint32_t                 version,
+                          const char*              runtime_version,
+                          uint32_t                 priority,
+                          rocprofiler_client_id_t* client_id)
+    {
+        //If not the first tool to register, indicate that the tool doesn't want to do anything
+        if(priority > 0) return nullptr;
+
+        // (optional) Provide a name for this tool to rocprofiler
+        client_id->name = "ExampleTool";
+
+        // (optional) create configure data
+        static auto data = ToolData{ version,
+                                 runtime_version,
+                                 priority,
+                                 client_id };
+
+        // construct configure result
+        static auto cfg =
+            rocprofiler_tool_configure_result_t{ sizeof(rocprofiler_tool_configure_result_t),
+                                             &tool_init,
+                                             &tool_fini,
+                                             static_cast<void*>(&data) };
+
+        return &cfg;
+    }
+
+
+.. note::
+    ROCprofiler-SDK does NOT support calls to any runtime function (HSA, HIP, and so on) during tool initialization.
+    Invoking any functions from the runtimes results in a deadlock.
+
+For each tool that contains a ``rocprofiler_configure`` function and returns a non-null pointer to a ``rocprofiler_tool_configure_result_t`` struct, ROCprofiler-SDK invokes the ``initialize`` callback after completing the scan for all ``rocprofiler_configure`` symbols. In other words, ROCprofiler-SDK
+collects all ``rocprofiler_tool_configure_result_t`` instances before invoking the ``initialize`` member of any of these instances.
+When ROCprofiler-SDK invokes ``initialize`` function in a tool, this is the opportunity to create contexts:
+
+.. code-block:: cpp
+
+    #include <rocprofiler-sdk/rocprofiler.h>
+
+    namespace
+    {
+    int
+    tool_init(rocprofiler_client_finalize_t fini_func,
+              void* data_v)
+    {
+        // create a context
+        auto ctx = rocprofiler_context_id_t{0};
+        rocprofiler_create_context(&ctx);
+
+        // ... associate services with context ...
+
+        // start the context (optional)
+        rocprofiler_start_context(ctx);
+
+        return 0;
+    }
+    }
+
+Although not mandatory, it is recommended that tools store the context handles to control the data collection for the services associated with the context.
+
+Tool finalization
+------------------
+
+When the `initialize` callback is invoked in the tool, ROCprofiler-SDK provides a function pointer of type `rocprofiler_client_finalize_t`.
+The tool can invoke this function pointer to explicitly invoke the `finalize` callback from the `rocprofiler_tool_configure_result_t` instance:
+
+.. code-block:: cpp
+
+    #include <rocprofiler-sdk/rocprofiler.h>
+
+    namespace
+    {
+        int
+        tool_init(rocprofiler_client_finalize_t fini_func,
+                  void* data_v)
+        {
+            // ... see initialization section ...
+
+            // function, which
+            auto explicit_finalize = [](rocprofiler_client_finalize_t finalizer,
+                                        rocprofiler_client_id_t* client_id)
+            {
+                std::this_thread::sleep_for(std::chrono::seconds{ 10 });
+                finalizer(client_id);
+            };
+
+            // start the context
+            rocprofiler_start_context(ctx);
+
+            // dispatch a background thread to explicitly finalize after 10 seconds
+            std::thread{ explicit_finalize, fini_func, static_cast<ToolData*>(data_v)->client_id }.detach();
+
+            return 0;
+        }
+    }
+
+Otherwise, ROCprofiler-SDK invokes the `finalize` callback via an `atexit` handler.
+
+Full rocprofiler_configure sample
+----------------------------------
+
+All the code snippets from the previous sections are combined here to demonstrate complete ROCProfiler configuration.
+
+.. code-block:: cpp
+
+    #include <rocprofiler-sdk/registration.h>
+
+    namespace
+    {
+    struct rocp_tool_data
+    {
+        uint32_t                              version;
+        const char*                           runtime_version;
+        uint32_t                              priority;
+        rocprofiler_client_id_t               client_id;
+        rocprofiler_client_finalize_t         finalizer;
+        std::vector<rocprofiler_context_id_t> contexts;
+    };
+
+    void
+    tool_tracing_callback(rocprofiler_callback_tracing_record_t record,
+                        rocprofiler_user_data_t*              user_data,
+                        void*                                 callback_data);
+
+    int
+    tool_init(rocprofiler_client_finalize_t fini_func,
+            void* tool_data_v)
+    {
+        rocp_tool_data* tool_data = static_cast<rocp_tool_data*>(tool_data_v);
+
+        // Save the finalizer function
+        tool_data->finalizer = fini_func;
+
+        // create a context
+        auto ctx = rocprofiler_context_id_t{0};
+        rocprofiler_create_context(&ctx);
+
+        // Save your contexts
+        tool_data->contexts.emplace_back(ctx);
+
+        // Associate code object tracing with this context
+        rocprofiler_configure_callback_tracing_service(
+            ctx,
+            ROCPROFILER_CALLBACK_TRACING_CODE_OBJECT,
+            nullptr,
+            0,
+            tool_tracing_callback,
+            tool_data);
+
+        // ... Associate services with contexts ...
+
+        return 0;
+    }
+
+    void
+    tool_fini(void* tool_data);
+    }
+
+    extern "C"
+    {
+    rocprofiler_tool_configure_result_t*
+    rocprofiler_configure(uint32_t                 version,
+                        const char*              runtime_version,
+                        uint32_t                 priority,
+                        rocprofiler_client_id_t* client_id)
+    {
+        // (optional) Provide a name for this tool to rocprofiler
+        client_id->name = "ExampleTool";
+
+        // Info provided back to tool_init and tool_fini
+        auto* my_tool_data = new rocp_tool_data{ version,
+                                                runtime_version,
+                                                priority,
+                                                client_id,
+                                                nullptr };
+
+        // Create configure data
+        static auto cfg =
+            rocprofiler_tool_configure_result_t{ sizeof(rocprofiler_tool_configure_result_t),
+                                                &tool_init,
+                                                &tool_fini,
+                                                my_tool_data };
+
+        return &cfg;
+    }

projects/rocprofiler-sdk/source/docs/conceptual/comparing-with-legacy-tools.rst

@@ -0,0 +1,448 @@
+.. meta::
+  :description: ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software
+  :keywords: ROCprofiler-SDK tool, ROCprofiler-SDK library, rocprofv3, ROCm, API, reference
+
+.. _comparing-with-legacy-tools:
+
+========================================================
+Comparing ROCprofiler-SDK to other ROCm profiling tools
+========================================================
+
+ROCprofiler-SDK is an improved version of ROCm profiling tools that enables more efficient implementations and better thread safety while avoiding problems that plague the former implementations of ROCProfiler and ROCTracer.
+Here are the distinct ROCprofiler-SDK features, which also highlight the improvements over ROCProfiler and ROCTracer:
+
+- Improved tool initialization
+- Support for simultaneous use of the same services by multiple tools
+- Simplified control of one or more data collection services
+- Improved error checking and logging
+- Backward ABI compatibility
+- PC sampling (beta implementation)
+
+The former implementations allow a tool to access any of the services provided by ROCProfiler or ROCTracer, such as API tracing and kernel tracing, by calling ``roctracer_init()`` when an ROCm runtime is initially loaded.
+As the calling tool is not required to specify during initialization, the services it needs to use, the libraries must be effectively prepared for any service to be available anytime.
+This behavior introduces unnecessary overhead and makes thread-safe data management difficult, as tools generally don't use all the available services.
+For example, ROCTracer always installs wrappers around every runtime API and adds indirection overhead through the ROCTracer library to check for the current service configuration in a thread-safe manner.
+
+ROCprofiler-SDK introduces `context` to solve the preceding issues. Contexts are effectively bundles of service configurations. ROCprofiler-SDK provides a single opportunity for a tool to create as many contexts as required.
+A tool can group all services into one context, create one context per service, or choose a mix.
+This change in the design allows ROCprofiler-SDK to be aware of the services that might be requested by a tool at any given time.
+The design change empowers ROCprofiler-SDK to:
+
+- Avoid unnecessary preparation for services that are never used. If no registered contexts request HSA API tracing, no wrappers need to be generated.
+- Perform more extensive checks during service specification and inform a tool about potential issues early.
+- Allow multiple tools to use certain services simultaneously.
+- Improve thread safety without introducing parallel bottlenecks.
+- Manage internal data and allocations more efficiently.
+
+===================================================================================================
+Comparing command-line tool options: ROCprofiler(rocprof, rocprofv2) and ROCprofiler-SDK(rocprofv3)
+===================================================================================================
+
+ROCprofiler-SDK introduces a new command-line tool, `rocprofv3`, which is a more efficient and flexible version of the ROCprofiler tool.
+
+.. list-table:: Comparison of ROCprofiler Command-Line Tool's options
+   :header-rows: 1
+
+   * - Category
+     - Feature
+     - rocprof
+     - rocprofv2
+     - rocprofv3
+     - Improvements
+     - Notes
+   * - Basic tracing options
+     - HIP Trace
+     - `--hip-trace`
+     - `--hip-api`, `--hip-trace`
+     - `--hip-trace`
+     - No change
+     - | rocprof and rocprofv2 `--hip-trace` options include kernel dispatches and memory copy activities,
+       | which is not the case in rocprofv3
+   * - Basic tracing options
+     - HSA Trace
+     - `--hsa-trace`
+     - `--hsa-trace`
+     - `--hsa-trace`
+     - No change
+     - | rocprof and rocprofv2 `--hsa-trace` options include kernel dispatches and memory copy activities,
+       | which is not the case in rocprofv3
+   * - Basic tracing options
+     - Scratch Memory Trace
+     - *Not Available*
+     - *Not Available*
+     - `--scratch-memory-trace`
+     - New option to trace scratch memory operations
+     -
+   * - Basic tracing options
+     - Marker Trace (ROCTx)
+     - `--roctx-trace`
+     - `--roctx-trace`
+     - `--marker-trace`
+     - Improved ROCTx library with more features
+     -
+   * - Basic tracing options
+     - Memory Copy Trace
+     - Part of HIP and HSA Traces
+     - Part of HIP and HSA Traces
+     - `--memory-copy-trace`
+     - Provides granularity for memory move operations
+     -
+   * - Basic tracing options
+     - Memory allocation Trace
+     - *Not Available*
+     - *Not Available*
+     - `--memory-allocation-trace`
+     - New option for collecting Memory Allocation Traces. Displays starting address, allocation size, and agent where allocation occurred.
+     -
+   * - Basic tracing options
+     - Kernel Trace
+     - `--kernel-trace`
+     - `--kernel-trace`
+     - `--kernel-trace`
+     - Performance improvement.
+     -
+   * - Granular tracing options
+     - HIP runtime trace
+     - Part of `--hip-trace` option
+     - Part of `--hip-trace` option
+     - `--hip-runtime-trace`
+     - For collecting HIP Runtime API Traces, e.g. public HIP API functions starting with 'hip' (i.e. hipSetDevice).
+     -
+   * - Granular tracing options
+     - HIP compiler trace
+     - *Not Available*
+     - *Not Available*
+     - `--hip-compiler-trace`
+     - For collecting HIP Compiler generated code Traces, e.g. HIP API functions starting with '__hip' (i.e. __hipRegisterFatBinary).
+     -
+   * - Granular tracing options
+     - HSA core API trace
+     - Part of `--hsa-trace` option
+     - Part of `--hsa-trace` option
+     - `--hsa-core-trace`
+     - New option for collecting only HSA API Traces (core API), e.g. HSA functions prefixed with only `hsa_` (i.e. hsa_init)
+     -
+   * - Granular tracing options
+     - HSA AMD trace
+     - Part of `--hsa-trace` option
+     - Part of `--hsa-trace` option
+     - `--hsa-amd-trace`
+     - For collecting HSA API Traces (AMD-extension API), e.g. HSA function prefixed with `hsa_amd_` (i.e. hsa_amd_coherency_get_type)
+     -
+   * - Granular tracing options
+     - HSA Image Extension trace
+     - Part of `--hsa-trace` option
+     - Part of `--hsa-trace` option
+     - `--hsa-image-trace`
+     - New option for collecting HSA API Traces (Image-extension API), e.g. HSA functions prefixed with only `hsa_ext_image_` (i.e. hsa_ext_image_get_capability).
+     -
+   * - Granular tracing options
+     - HSA Finalizer trace
+     - Part of `--hsa-trace` option
+     - Part of `--hsa-trace` option
+     - `--hsa-finalizer-trace`
+     - New option for collecting HSA API Traces (Finalizer-extension API), e.g. HSA functions prefixed with only `hsa_ext_program_` (i.e. hsa_ext_program_create)
+     -
+   * - Advanced tracing options
+     - Kokkos trace
+     - *Not Available*
+     - *Not Available*
+     - `--kokkos-trace`
+     - New option to enable built-in Kokkos Tools support (implies --marker-trace and --kernel-rename)
+     -
+   * - Advanced tracing options
+     - RCCL trace
+     - *Not Available*
+     - *Not Available*
+     - `--rccl-trace`
+     - For collecting RCCL (ROCm Communication Collectives Library. Also pronounced as 'Rickle' ) Traces
+     -
+   * - Advanced tracing options
+     - Scratch memory trace
+     - *Not Available*
+     - *Not Available*
+     - `--scratch-memory-trace`
+     - Collecting scratch memory event traces.
+     -
+   * - Advanced tracing options
+     - rocDecode trace
+     - *Not Available*
+     - *Not Available*
+     - `--rocdecode-trace`
+     - Tracing rocDecode library.
+     -
+   * - Advanced tracing options
+     - rocJPEG trace
+     - *Not Available*
+     - *Not Available*
+     - `--rocjpeg-trace`
+     - Tracing rocJPEG library.
+     -
+   * - Aggregate tracing options
+     - Sys Trace
+     - `--sys-trace` [hip-trace|hsa-trace|roctx-trace|kernel-trace]
+     - `--sys-trace` [hip-trace|hsa-trace|roctx-trace|kernel-trace]
+     - ` -s, --sys-trace` [hip-trace|hsa-trace|scratch-trace|memory-copy-trace|roctx-trace|kernel-trace]
+     - Extends the sys trace options with more features
+     -
+   * - Aggregate tracing options
+     - Runtime Trace
+     - *Not available*
+     - *Not available*
+     - ` -r, --runtime-trace` [hip-runtime-trace|scratch-trace|memory-copy-trace|roctx-trace|kernel-trace]
+     - New option to aggregate trace operations
+     -
+   * - Kernel naming options
+     - Kernel Name Mangling
+     - *Not Available*
+     - *Not Available*
+     - `-M`, `--mangled-kernels`
+     - New option for mangled  kernel names
+     -
+   * - Kernel naming options
+     - Kernel Name Truncation
+     - `--basenames  <on|off>`
+     - `--basenames`
+     - `-T`, `--truncate-kernels`
+     - New option for truncating the demangled  kernel names
+     -
+   * - Kernel naming options
+     - Kernel Rename
+     - `--roctx-rename`
+     - *Not available*
+     - `--kernel-rename`
+     - New option to use region names defined by roctxRangePush/roctxRangePop regions to rename the kernels
+     -
+   * - Post-processing tracing options
+     - Statistics
+     - --stats
+     - *Not Available*
+     - --stats
+     - Statistics for the collected traces
+     -
+   * - Post-processing tracing options
+     - Summary
+     - *Not available*
+     - *Not available*
+     - `-S, --summary`
+     - New option to output a single summary of tracing data after the profiling session
+     - `rocprof` generated the post-processing step's summary, stats, JSON, and database files with much less information.
+   * - Post-processing tracing options
+     - Summary Per Domain
+     - *Not available*
+     - *Not available*
+     - `-D, --summary-per-domain`
+     - New option to output summary for each tracing domain after the profiling session
+     - `rocprof --stats` option had less number of domains in the summary reports than `rocprofv3`
+   * - Post-processing tracing options
+     - Summary Groups
+     - *Not available*
+     - *Not available*
+     - `--summary-groups REGULAR_EXPRESSION`
+     - New option to output a summary for each set of domains matching the regular expression, e.g. 'KERNEL_DISPATCH|MEMORY_COPY' will generate a summary from all the tracing data in the KERNEL_DISPATCH and MEMORY_COPY domains
+     -
+   * - Summary options
+     - Summary Output File
+     - *Not available*
+     - *Not available*
+     - `--summary-output-file SUMMARY_OUTPUT_FILE`
+     - New option to output summary to a file, stdout, or stderr (default: stderr)
+     -
+   * - Summary options
+     - Summary Units
+     - *Not available*
+     - *Not available*
+     - `-u , --summary-units`
+     - New option to output summary in desired time units {sec,msec,usec,nsec}
+     -
+   * - Display options
+     - List available basic and derived metrics and PC sampling configurations
+     - `--list-basic`, `--list-derived`
+     - `--list-counters`
+     - `-L`, `--list-avail`
+     - A valid YAML is supported for this option now
+     -
+   * - Perfetto-specific options
+     - Perfetto data collection backend
+     - *Not available*
+     - *Not available*
+     - `--perfetto-backend` {in-process,system}
+     - New option for perfetto data collection backend. 'system' mode requires starting traced and perfetto daemons
+     - `rocprofv2` used only in-process collection for perfetto plugin, However, `rocprofv3` gives the user the option.
+   * - Perfetto-specific options
+     - Perfetto Buffer Size
+     - *Not available*
+     - Setting env variable `rocprofiler_PERFETTO_MAX_BUFFER_SIZE_KIB` to the desired buffer size
+     - `--perfetto-buffer-size` {KB}
+     - New option to define size of buffer for perfetto output in KB. default: 1 GB
+     -
+   * - Perfetto-specific options
+     - Perfetto Buffer fill Policy
+     - *Not available*
+     - *Not available*
+     - `--perfetto-buffer-fill-policy` {discard,ring_buffer}
+     - New option or handling new records when perfetto has reached the buffer limit
+     - `rocprofv2` always used `TraceConfig_BufferConfig_FillPolicy_RING_BUFFER` fill policy.
+   * - Perfetto-specific options
+     - Perfetto shared memory size
+     - *Not available*
+     - *Not available*
+     - `--perfetto-shmem-size-hint` KB
+     - New option to define perfetto shared memory size hint in KB. default: 64 KB
+     -
+   * - Filtering options
+     - Kernel Filtration options for Counter Collection
+     - Supported in input.xml file (supports range, gpu and kernel filtration)
+     - kernel: <kernel_name> (can only be provided in input.txt file)
+     - `--kernel-include-regex`, `--kernel-exclude-regex`, `--kernel-iteration-range`
+     - Extensive control over output options using regular expressions
+     -
+   * - I/O options
+     - Output Directory
+     - `-d` <data directory>
+     - `-d`   | `--output-directory`
+     - `-d` OUTPUT_DIRECTORY, `--output-directory` OUTPUT_DIRECTORY
+     - rocprofv3 supports special keys for runtime values, e.g. %pid% gets replaced by the process ID
+     -
+   * - I/O options
+     - Output File
+     - `-o` <output file>
+     - `-o`   | `--output-file-name`
+     - `-o` OUTPUT_FILE, `--output-file` OUTPUT_FILE
+     - rocprofv3 supports special keys for runtime values, e.g. %pid% gets replaced by the process ID
+     -
+   * - I/O options
+     - Logging
+     - Minimal logging via environment variable
+     - Minimal logging via environment variable
+     - --log-level {fatal,error,warning,info,trace,env}
+     - Extensive logging options
+     -
+   * - I/O options
+     - Plugins
+     - *Not Available*
+     - plugin support for different output formats
+     - Replaced by `--output-format` option
+     - Not needed as rocprofv3 supports multiple output formats
+     -
+   * - I/O options
+     - Output Formats
+     - CSV, JSON (Chrome-Tracing format)
+     - CSV, JSON (Chrome-Tracing format), Perfetto, CTF
+     - CSV, JSON (custom schema), Perfetto, OTF2
+     - | # Multiple output formats can be supported in single run.
+       | # OTF2 can visualize larger trace files compared to perfetto.
+     - The Perfetto UI does not accept the JSON output format produced by rocprofv3. Perfetto is dropping support for the JSON Chrome tracing format in favor of the binary Perfetto protobuf format (``.pftrace`` extension), which is supported by rocprofv3.
+   * - I/O options
+     - Counter Collection
+     - Supports input text and XML format
+     - Only supports input text format
+     - Input support for text, YAML and JSON formats
+     - | # It's not possible to check for valid text file. Hence rocprofv3 supports strongly typed input formats.
+       | # YAML and JSON formats are more readable and easy to maintain.
+       | # Allows flexibility to add more features for the tool input
+     -
+   * - I/O options
+     - Command-line Counter Collection
+     - *Not Available*
+     - *Not Available*
+     - `--pmc`
+     - New option to collect performance counters from command line. Counters should be comma OR space separated in case of more than 1 counters
+     -
+   * - I/O options
+     - Providing Custom metrics file
+     - `-m`  <metric file>
+     - `-m`  <metric file>
+     - `-E`  <metric file> --pmc <counter>
+     - In rocprofv3, this option has changed to provide a file with custom metrics and collect performance counters from the command line using --pmc option
+     -
+   * - Advanced options
+     - Preload
+     - *Not Available*
+     - *Not Available*
+     - --preload
+     - Libraries to prepend to LD_PRELOAD (usually for sanitizers)
+     -
+   * - Trace Control options
+     - Trace Period
+     - `--trace-period`
+     - `-tp | --trace-period`
+     - `-P  |--collection-period`,`--collection-period-unit`
+     - Users can specify multiple configurations, each defined by a triplet in the format `start_delay:collection_time:repeat`, with the ability to change the unit of time in the given configurations.
+     -
+   * - Trace Control options
+     - Trace start
+     -  `--trace-start <on|off>`
+     - *Not available*
+     - *Not available*
+     - Not yet in rocprofv3
+     -
+   * - Trace Control options
+     - Flush Interval
+     - `--flush-rate`
+     - `--flush-interval`
+     - *Not available*
+     - Not applicable for rocprofv3
+     -
+   * - Trace Control options
+     - Merge Traces
+     - `--merge-traces`
+     - *Not available*
+     - *Not available*
+     - Not yet in rocprofv3
+     -
+   * - PC Sampling options
+     - PC Sampling`
+     - *Not available*
+     - *Not available*
+     - `--pc-sampling-beta-enabled`
+     - Enable pc sampling support; beta version.
+     -
+   * - Legacy options
+     - Timestamp On/Off
+     - `--timestamp <on|off>`
+     - *Not available*
+     - *Not available*
+     - Not applicable for rocprofv3
+     -
+   * - Legacy options
+     - Context wait
+     - `--ctx-wait`
+     - *Not available*
+     - *Not available*
+     - Not applicable for rocprofv3
+     -
+   * - Legacy options
+     - Context Limit
+     - `--ctx-limit <max number>`
+     - *Not available*
+     - *Not available*
+     - Not applicable for rocprofv3
+     -
+   * - Legacy options
+     - Code Object Tracking
+     - `--obj-tracking <on|off>`
+     - Always ``ON`` in rocprofv2
+     - Always ``ON`` in rocprofv3
+     -
+     -
+   * - Legacy options
+     - Heartbeat
+     - `--heartbeat <rate sec>`
+     - *Not available*
+     - *Not available*
+     - Not applicable for rocprofv3
+     -
+
+
+========================================================
+Timing Difference Between rocprofv3 and rocprofv1/v2
+========================================================
+
+``rocprofv3`` has improved the accuracy of timing information by reducing the tool overhead required to collect data and reducing the interference to the timing of the kernel being measured. The result of this work is a reduction in variance of kernel times received for the same kernel execution and more accurate timing in general. These changes have not been backported (and will not be backported) to rocprofv1/v2, so there can be substantial (20%) differences in execution time reported by v1/v2 vs v3 for a single kernel execution. Over a large number of samples of the same kernel, the difference in average execution time is in the low single digit percentage time with a much tighter variance of results on rocprofv3. We have included testing in the test suite to verify the timing information outputted by rocprofv3 to ensure that the values we are returning are accurate.
+
+========================================================
+Default run of rocprofv3 and rocprofv1/v2
+========================================================
+
+``rocprofv3`` has a different default behavior than rocprofv1/v2 when being run without any option. The default behavior of rocprofv3 is to collect all available agents on the system and to output it in ``csv`` format. The default behavior of rocprofv1/v2 was to output the `kernel traces` in CSV format. In rocprofv3, kernel traces can be obtained by using ``--kernel-trace`` option.

projects/rocprofiler-sdk/source/docs/conf.py

@@ -0,0 +1,105 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+
+import os
+import sys
+import subprocess as sp
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath(".."))
+
+
+def install(package):
+    sp.call([sys.executable, "-m", "pip", "install", package])
+
+
+# Check if we're running on Read the Docs' servers
+read_the_docs_build = os.environ.get("READTHEDOCS", None) == "True"
+
+_srcdir = os.path.realpath(os.path.join(os.getcwd(), "../.."))
+
+
+def build_doxyfile():
+    sp.run(
+        [
+            "cmake",
+            f"-DSOURCE_DIR={_srcdir}",
+            "-DPROJECT_NAME='ROCprofiler-SDK'",
+            f"-P {_srcdir}/source/docs/generate-doxyfile.cmake",
+        ]
+    )
+
+
+build_doxyfile()
+
+# -- Project information -----------------------------------------------------
+project = "Rocprofiler SDK"
+copyright = "2023-2025, Advanced Micro Devices, Inc."
+author = "Advanced Micro Devices, Inc."
+
+project_root = os.path.normpath(os.path.join(os.getcwd(), "..", ".."))
+version = open(os.path.join(project_root, "VERSION")).read().strip()
+# The full version, including alpha/beta/rc tags
+release = version
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "rocm_docs",
+    "rocm_docs.doxygen",
+]
+
+doxygen_root = "."
+doxysphinx_enabled = True
+
+breathe_projects = {
+    "rocprofiler-sdk": "_doxygen/rocprofiler-sdk/xml",
+    "roctx": "_doxygen/roctx/xml",
+}
+breathe_default_project = "rocprofiler-sdk"
+
+doxyfile = "rocprofiler-sdk.dox"
+
+external_projects_current_project = "rocprofiler-sdk"
+external_projects = []
+
+master_doc = "index"
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md"]
+external_toc_path = "./_toc.yml"
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+suppress_warnings = ["etoc.toctree"]
+nitpick_ignore = [
+    ("cpp:identifier", "uint32_t"),
+    ("cpp:identifier", "uint64_t"),
+    ("cpp:identifier", "hsa_agent_s"),
+    ("cpp:identifier", "ihipStream_t"),
+]
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+
+html_theme = "rocm_docs_theme"
+html_theme_options = {"flavor": "rocm"}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_title = f"ROCprofiler-SDK {version} Documentation"

projects/rocprofiler-sdk/source/docs/data/counter_collection.csv

@@ -0,0 +1,5 @@
+"Correlation_Id","Dispatch_Id","Agent_Id","Queue_Id","Process_Id","Thread_Id","Grid_Size","Kernel_Id","Kernel_Name","Workgroup_Size","LDS_Block_Size","Scratch_Size","VGPR_Count","Accum_VGPR_Count","SGPR_Count","Counter_Name","Counter_Value","Start_Timestamp","End_Timestamp"
+1,1,"Agent 1",1,15606,15606,1048576,17,"void addition_kernel<float>(float*, float const*, float const*, int, int)",64,0,0,8,0,16,"SQ_WAVES",16384.000000,3200098838431081,3200098838483232
+2,2,"Agent 1",1,15606,15606,1048576,20,"subtract_kernel(float*, float const*, float const*, int, int)",64,0,0,8,0,16,"SQ_WAVES",16384.000000,3200098838589014,3200098838638794
+3,3,"Agent 1",1,15606,15606,1048576,19,"multiply_kernel(float*, float const*, float const*, int, int)",64,0,0,8,0,16,"SQ_WAVES",16384.000000,3200098838746207,3200098838793025
+4,4,"Agent 1",1,15606,15606,1048576,18,"divide_kernel(float*, float const*, float const*, int, int)",64,0,0,12,0,16,"SQ_WAVES",16384.000000,3200098838879399,3200098838927550

projects/rocprofiler-sdk/source/docs/data/hip_api_stats.csv

@@ -0,0 +1,18 @@
+"Name","Calls","TotalDurationNs","AverageNs","Percentage","MinNs","MaxNs","StdDev"
+"hipStreamCreateWithFlags",4,262497406,65624351.500000,85.15,3991286,249121840,122332531.343496
+"hipGetDeviceCount",1,32505687,32505687.000000,10.54,32505687,32505687,0.00000000e+00
+"hipHostMalloc",12,6096409,508034.083333,1.98,443793,548024,39236.753678
+"hipFree",12,1994421,166201.750000,0.6470,7790,1036046,299086.860470
+"hipMemcpyAsync",12,1368378,114031.500000,0.4439,2490,764044,249308.051619
+"hipMallocAsync",12,927255,77271.250000,0.3008,51540,107671,20487.475966
+"hipStreamSynchronize",12,870486,72540.500000,0.2824,140,866606,250065.900069
+"hipLaunchKernel",16,692734,43295.875000,0.2247,1000,670044,167133.656647
+"hipStreamDestroy",4,619905,154976.250000,0.2011,92901,339252,122852.320356
+"hipDeviceSynchronize",4,404252,101063.000000,0.1311,570,385212,189518.505401
+"hipHostFree",12,271202,22600.166667,0.0880,11950,34950,7480.268600
+"__hipRegisterFatBinary",1,9000,9000.000000,2.920e-03,9000,9000,0.00000000e+00
+"__hipRegisterFunction",4,6150,1537.500000,1.995e-03,230,5370,2555.091323
+"__hipPushCallConfiguration",16,2460,153.750000,7.980e-04,70,1140,267.503894
+"__hipPopCallConfiguration",16,2000,125.000000,6.488e-04,70,680,151.613544
+"hipGetLastError",16,1270,79.375000,4.120e-04,50,440,96.295985
+"hipSetDevice",1,660,660.000000,2.141e-04,660,660,0.00000000e+00

projects/rocprofiler-sdk/source/docs/data/hip_compile_trace.csv

@@ -0,0 +1,7 @@
+"Domain","Function","Process_Id","Thread_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
+"HIP_COMPILER_API_EXT","__hipRegisterFatBinary",15,15,1,1055015439953054,1055015439976484
+"HIP_COMPILER_API_EXT","__hipRegisterFunction",15,15,2,1055015439992584,1055015440011104
+"HIP_COMPILER_API_EXT","__hipRegisterFunction",15,15,3,1055015440011744,1055015440013824
+"HIP_COMPILER_API_EXT","__hipRegisterFunction",15,15,4,1055015440014244,1055015440014534
+"HIP_COMPILER_API_EXT","__hipRegisterFunction",15,15,5,1055015440014854,1055015440015524
+

projects/rocprofiler-sdk/source/docs/data/hip_domain_stats.csv

@@ -0,0 +1,2 @@
+"Name","Calls","TotalDurationNs","AverageNs","Percentage","MinNs","MaxNs","StdDev"
+"HIP_API",13,458514859,35270373.769231,100.00,2300,352276613,99315857.546240

projects/rocprofiler-sdk/source/docs/data/hip_runtime_trace.csv

@@ -0,0 +1,9 @@
+"Domain","Function","Process_Id","Thread_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
+"HIP_RUNTIME_API_EXT","hipGetDevicePropertiesR0600",238,238,1,1191915574691984,1191915687784011
+"HIP_RUNTIME_API_EXT","hipMalloc",238,238,2,1191915691312459,1191915691388696
+"HIP_RUNTIME_API_EXT","hipMalloc",238,238,3,1191915691390637,1191915691423279
+"HIP_RUNTIME_API_EXT","hipMemcpy",238,238,4,1191915691439107,1191916547828448
+"HIP_RUNTIME_API_EXT","hipLaunchKernel",238,238,5,1191916547842972,1191916548408842
+"HIP_RUNTIME_API_EXT","hipMemcpy",238,238,6,1191916548412677,1191916550217834
+"HIP_RUNTIME_API_EXT","hipFree",238,238,7,1191916562618151,1191916562789093
+"HIP_RUNTIME_API_EXT","hipFree",238,238,8,1191916562790923,1191916562836351

projects/rocprofiler-sdk/source/docs/data/hip_trace.csv

@@ -0,0 +1,18 @@
+"Domain","Function","Process_Id","Thread_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
+"HIP_COMPILER_API_EXT","__hipRegisterFatBinary",15,15,1,1055015439953054,1055015439976484
+"HIP_COMPILER_API_EXT","__hipRegisterFunction",15,15,2,1055015439992584,1055015440011104
+"HIP_COMPILER_API_EXT","__hipRegisterFunction",15,15,3,1055015440011744,1055015440013824
+"HIP_COMPILER_API_EXT","__hipRegisterFunction",15,15,4,1055015440014244,1055015440014534
+"HIP_COMPILER_API_EXT","__hipRegisterFunction",15,15,5,1055015440014854,1055015440015524
+"HIP_RUNTIME_API_EXT","hipGetDeviceCount",15,15,6,1055015440617618,1055015539800733
+"HIP_RUNTIME_API_EXT","hipSetDevice",15,15,7,1055015539819503,1055015539821693
+"HIP_RUNTIME_API_EXT","hipDeviceSynchronize",15,15,8,1055015539832333,1055015539840903
+"HIP_RUNTIME_API_EXT","hipStreamCreateWithFlags",15,15,9,1055015539861673,1055015865247140
+"HIP_RUNTIME_API_EXT","hipHostMalloc",15,15,10,1055015865309761,1055015865849494
+"HIP_RUNTIME_API_EXT","hipHostMalloc",15,15,11,1055015865850944,1055015866265546
+"HIP_RUNTIME_API_EXT","hipHostMalloc",15,15,12,1055015866266646,1055015867082900
+"HIP_RUNTIME_API_EXT","hipMallocAsync",15,15,13,1055015867356542,1055015867662314
+"HIP_RUNTIME_API_EXT","hipMallocAsync",15,15,14,1055015867664174,1055015867937465
+"HIP_RUNTIME_API_EXT","hipMallocAsync",15,15,15,1055015867938815,1055015868219987
+"HIP_RUNTIME_API_EXT","hipMemcpyAsync",15,15,16,1055015868240137,1055015917307652
+"HIP_RUNTIME_API_EXT","hipMemcpyAsync",15,15,17,1055015917337263,1055015917360493

projects/rocprofiler-sdk/source/docs/data/hsa_api_trace.csv

@@ -0,0 +1,11 @@
+"Domain","Function","Process_Id","Thread_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
+"HSA_CORE_API","hsa_system_get_major_extension_table",197,197,1,1507843974724237,1507843974724947
+"HSA_CORE_API","hsa_agent_get_info",197,197,3,1507843974754471,1507843974755014
+"HSA_AMD_EXT_API","hsa_amd_memory_pool_get_info",197,197,5,1507843974761705,1507843974762398
+"HSA_AMD_EXT_API","hsa_amd_memory_pool_get_info",197,197,6,1507843974763901,1507843974764030
+"HSA_AMD_EXT_API","hsa_amd_memory_pool_get_info",197,197,7,1507843974765121,1507843974765224
+"HSA_AMD_EXT_API","hsa_amd_memory_pool_get_info",197,197,8,1507843974766196,1507843974766328
+"HSA_AMD_EXT_API","hsa_amd_memory_pool_get_info",197,197,9,1507843974767534,1507843974767641
+"HSA_AMD_EXT_API","hsa_amd_memory_pool_get_info",197,197,10,1507843974768639,1507843974768779
+"HSA_AMD_EXT_API","hsa_amd_agent_iterate_memory_pools",197,197,4,1507843974758768,1507843974769238
+"HSA_CORE_API","hsa_agent_get_info",197,197,11,1507843974771091,1507843974771537

projects/rocprofiler-sdk/source/docs/data/hsa_core_api_trace.csv

@@ -0,0 +1,34 @@
+"Domain","Function","Process_Id","Thread_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
+"HSA_CORE_API","hsa_system_get_major_extension_table",57,57,1,1056813747808832,1056813747809252
+"HSA_CORE_API","hsa_agent_get_info",57,57,3,1056813747826572,1056813747826672
+"HSA_CORE_API","hsa_agent_get_info",57,57,4,1056813747837582,1056813747837622
+"HSA_CORE_API","hsa_agent_get_info",57,57,5,1056813747838542,1056813747838582
+"HSA_CORE_API","hsa_agent_get_info",57,57,6,1056813747839042,1056813747839082
+"HSA_CORE_API","hsa_agent_get_info",57,57,7,1056813747839512,1056813747839622
+"HSA_CORE_API","hsa_iterate_agents",57,57,2,1056813747821012,1056813747839832
+"HSA_CORE_API","hsa_agent_get_info",57,57,8,1056813747843832,1056813747844132
+"HSA_CORE_API","hsa_agent_get_info",57,57,9,1056813747844482,1056813747844542
+"HSA_CORE_API","hsa_agent_iterate_isas",57,57,10,1056813747849402,1056813747850422
+"HSA_CORE_API","hsa_isa_get_info_alt",57,57,11,1056813747853542,1056813747875253
+"HSA_CORE_API","hsa_isa_get_info_alt",57,57,12,1056813747875883,1056813747878353
+"HSA_CORE_API","hsa_agent_get_info",57,57,13,1056813747886343,1056813747886403
+"HSA_CORE_API","hsa_agent_get_info",57,57,54,1056813748282015,1056813748282085
+"HSA_CORE_API","hsa_system_get_info",57,57,55,1056813748282465,1056813748282505
+"HSA_CORE_API","hsa_signal_create",57,57,56,1056813749083419,1056813749085399
+"HSA_CORE_API","hsa_agent_get_info",57,57,57,1056813749741363,1056813749741443
+"HSA_CORE_API","hsa_queue_create",57,57,58,1056813749744053,1056813856914188
+"HSA_CORE_API","hsa_signal_create",57,57,59,1056813857149169,1056813857154109
+"HSA_CORE_API","hsa_signal_create",57,57,60,1056813857154929,1056813857155389
+"HSA_CORE_API","hsa_signal_create",57,57,61,1056813857155949,1056813857156429
+"HSA_CORE_API","hsa_signal_create",57,57,62,1056813857157169,1056813857157349
+"HSA_CORE_API","hsa_executable_create_alt",57,57,63,1056813965439362,1056813965466952
+"HSA_CORE_API","hsa_code_object_reader_create_from_memory",57,57,64,1056813965476642,1056813965587493
+"HSA_CORE_API","hsa_executable_load_agent_code_object",57,57,65,1056813965592483,1056813965965295
+"HSA_CORE_API","hsa_signal_create",57,57,67,1056813966149786,1056813966151706
+"HSA_CORE_API","hsa_signal_wait_scacquire",57,57,68,1056813966156596,1056813966158646
+"HSA_CORE_API","hsa_signal_destroy",57,57,69,1056813966162276,1056813966163746
+"HSA_CORE_API","hsa_executable_freeze",57,57,66,1056813965973105,1056813966778050
+"HSA_CORE_API","hsa_executable_get_symbol_by_name",57,57,70,1056813966800070,1056813966801880
+"HSA_CORE_API","hsa_executable_symbol_get_info",57,57,71,1056813966805750,1056813966805980
+"HSA_CORE_API","hsa_executable_symbol_get_info",57,57,72,1056813966806300,1056813966806340
+

projects/rocprofiler-sdk/source/docs/data/kernel_names.csv

@@ -0,0 +1,5 @@
+"Correlation_Id","Dispatch_Id","Agent_Id","Queue_Id","Process_Id","Thread_Id","Grid_Size","Kernel_Name","Workgroup_Size","LDS_Block_Size","Scratch_Size","VGPR_Count","SGPR_Count","Counter_Name","Counter_Value"
+4,4,1,1,36499,36499,1048576,"divide_kernel(float*, float const*, float const*, int, int)",64,0,0,12,16,"SQ_WAVES",16384
+8,8,1,2,36499,36499,1048576,"divide_kernel(float*, float const*, float const*, int, int)",64,0,0,12,16,"SQ_WAVES",16384
+12,12,1,3,36499,36499,1048576,"divide_kernel(float*, float const*, float const*, int, int)",64,0,0,12,16,"SQ_WAVES",16384
+16,16,1,4,36499,36499,1048576,"divide_kernel(float*, float const*, float const*, int, int)",64,0,0,12,16,"SQ_WAVES",16384

projects/rocprofiler-sdk/source/docs/data/kernel_trace.csv

@@ -0,0 +1,10 @@
+"Kind","Agent_Id","Queue_Id","Stream_Id","Thread_Id","Dispatch_Id","Kernel_Id","Kernel_Name","Correlation_Id","Start_Timestamp","End_Timestamp","LDS_Block_Size","Scratch_Size","VGPR_Count","Accum_VGPR_Count","SGPR_Count","Workgroup_Size_X","Workgroup_Size_Y","Workgroup_Size_Z","Grid_Size_X","Grid_Size_Y","Grid_Size_Z"
+"KERNEL_DISPATCH","Agent 4",1,1,834304,1,10,"void addition_kernel<float>(float*, float const*, float const*, int, int)",1,1550151853029637,1550151853042437,0,0,8,0,16,64,1,1,1024,1024,1
+"KERNEL_DISPATCH","Agent 4",1,1,834304,4,11,"divide_kernel(float*, float const*, float const*, int, int)",4,1550151853064037,1550151853075237,0,0,12,4,16,64,1,1,1024,1024,1
+"KERNEL_DISPATCH","Agent 4",1,1,834304,3,12,"multiply_kernel(float*, float const*, float const*, int, int)",3,1550151853052877,1550151853064037,0,0,8,0,16,64,1,1,1024,1024,1
+"KERNEL_DISPATCH","Agent 4",1,1,834304,2,13,"subtract_kernel(float*, float const*, float const*, int, int)",2,1550151853042437,1550151853050677,0,0,8,0,16,64,1,1,1024,1024,1
+"KERNEL_DISPATCH","Agent 4",2,2,834304,5,10,"void addition_kernel<float>(float*, float const*, float const*, int, int)",5,1550151853082957,1550151853094357,0,0,8,0,16,64,1,1,1024,1024,1
+"KERNEL_DISPATCH","Agent 4",2,2,834304,6,13,"subtract_kernel(float*, float const*, float const*, int, int)",6,1550151853094357,1550151853103517,0,0,8,0,16,64,1,1,1024,1024,1
+"KERNEL_DISPATCH","Agent 4",4,4,834304,13,10,"void addition_kernel<float>(float*, float const*, float const*, int, int)",13,1550151853164197,1550151853174037,0,0,8,0,16,64,1,1,1024,1024,1
+"KERNEL_DISPATCH","Agent 4",3,3,834304,12,11,"divide_kernel(float*, float const*, float const*, int, int)",12,1550151853148397,1550151853160837,0,0,12,4,16,64,1,1,1024,1024,1
+"KERNEL_DISPATCH","Agent 4",3,3,834304,11,12,"multiply_kernel(float*, float const*, float const*, int, int)",11,1550151853138477,1550151853148397,0,0,8,0,16,64,1,1,1024,1024,1

projects/rocprofiler-sdk/source/docs/data/kernel_trace_truncated.csv

@@ -0,0 +1,5 @@
+"Kind","Agent_Id","Queue_Id","Stream_Id","Thread_Id","Dispatch_Id","Kernel_Id","Kernel_Name","Correlation_Id","Start_Timestamp","End_Timestamp","LDS_Block_Size","Scratch_Size","VGPR_Count","Accum_VGPR_Count","SGPR_Count","Workgroup_Size_X","Workgroup_Size_Y","Workgroup_Size_Z","Grid_Size_X","Grid_Size_Y","Grid_Size_Z"
+"KERNEL_DISPATCH","Agent 4",1,1,855217,1,10,"addition_kernel",1,1552082594648838,1552082594660478,0,0,8,0,16,64,1,1,1024,1024,1
+"KERNEL_DISPATCH","Agent 4",1,1,855217,4,11,"divide_kernel",4,1552082594696598,1552082594709678,0,0,12,4,16,64,1,1,1024,1024,1
+"KERNEL_DISPATCH","Agent 4",1,1,855217,3,12,"multiply_kernel",3,1552082594685158,1552082594696598,0,0,8,0,16,64,1,1,1024,1024,1
+"KERNEL_DISPATCH","Agent 4",1,1,855217,2,13,"subtract_kernel",2,1552082594660478,1552082594669158,0,0,8,0,16,64,1,1,1024,1024,1

projects/rocprofiler-sdk/source/docs/data/list-avail.txt

@@ -0,0 +1,26 @@
+GPU     :	0
+Name    :	gfx90a
+configs :
+   Method              :	host_trap
+   Unit                :	time
+   Min_Interval        :	1
+   Max_Interval        :	18446744073709551615
+   Flags               :	none
+
+GPU:0
+Name:gfx90a
+Counter_Name        :	processor_id_low
+Description         :	Constant value processor_id_low from agent properties
+
+
+Counter_Name        :	ALUStalledByLDS
+Description         :	The percentage of GPUTime ALU units are stalled by the LDS input queue being full or the output queue being not ready. If there are LDS bank conflicts, reduce them. Otherwise, try reducing the number of LDS accesses if possible. Value range: 0% (optimal) to 100% (bad).
+Expression          :	400*reduce(SQ_WAIT_INST_LDS,sum)/reduce(SQ_WAVES,sum)/reduce(GRBM_GUI_ACTIVE,max)
+Dimensions          :	DIMENSION_INSTANCE[0:0]
+
+Counter_Name        :	SQ_WAVES
+Description         :	Count number of waves sent to distributed sequencers (SQs). This value represents the number of waves that are sent to each SQ. This only counts new waves sent since the start of collection (for dispatch profiling this is the timeframe of kernel execution, for agent profiling it is the timeframe between start_context and read counter data). A sum of all SQ_WAVES values will give the total number of waves started by the application during the collection timeframe. Returns one value per-SE (aggregates of SIMD values).
+Block               :	SQ
+Dimensions          :	DIMENSION_INSTANCE[0:0] DIMENSION_SHADER_ENGINE[0:7]
+
+...

projects/rocprofiler-sdk/source/docs/data/marker_api_trace.csv

@@ -0,0 +1,6 @@
+"Domain","Function","Process_Id","Thread_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
+"MARKER_CORE_API","before hipLaunchKernel",717,717,1,1520113899312225,1520113899312225
+"MARKER_CORE_API","after hipLaunchKernel",717,717,4,1520113900128482,1520113900128482
+"MARKER_CORE_API","hipMemcpy",717,717,5,1520113900141100,1520113901483408
+"MARKER_CORE_API","hipLaunchKernel",717,717,3,1520113899684965,1520113901491622
+"MARKER_CORE_API","hipLaunchKernel range",717,0,2,1520113899682208,1520113901495882

projects/rocprofiler-sdk/source/docs/data/memory_allocation_trace.csv

@@ -0,0 +1,7 @@
+"Kind","Operation","Agent_Id","Allocation_Size","Address","Correlation_Id","Start_Timestamp","End_Timestamp"
+"MEMORY_ALLOCATION","MEMORY_ALLOCATION_ALLOCATE",Agent 0,1024,0x7fb2d0005000,11,3721742710532634,3721742710584854
+"MEMORY_ALLOCATION","MEMORY_ALLOCATION_FREE",Agent 0,0,0x7fb2d0005000,12,3721742710596404,3721742710933366
+"MEMORY_ALLOCATION","MEMORY_ALLOCATION_ALLOCATE",Agent 0,1024,0x7fb2d0005000,13,3721742710941416,3721742710960916
+"MEMORY_ALLOCATION","MEMORY_ALLOCATION_FREE",Agent 0,0,0x7fb2d0005000,14,3721742710967236,3721742711197647
+"MEMORY_ALLOCATION","MEMORY_ALLOCATION_ALLOCATE",Agent 0,1024,0x7fb2d0005000,15,3721742711204077,3721742711219717
+"MEMORY_ALLOCATION","MEMORY_ALLOCATION_FREE",Agent 0,0,0x7fb2d0005000,16,3721742711225857,3721742711466018

projects/rocprofiler-sdk/source/docs/data/memory_copy_trace.csv

@@ -0,0 +1,5 @@
+"Kind","Direction","Stream_Id","Source_Agent_Id","Destination_Agent_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
+"MEMORY_COPY","MEMORY_COPY_HOST_TO_DEVICE",0,"Agent 0","Agent 4",1,1057963336487172,1057963336564212
+"MEMORY_COPY","MEMORY_COPY_HOST_TO_DEVICE",0,"Agent 0","Agent 4",2,1057963336783973,1057963336859334
+"MEMORY_COPY","MEMORY_COPY_DEVICE_TO_HOST",0,"Agent 4","Agent 0",23,1057963497396292,1057963497471732
+"MEMORY_COPY","MEMORY_COPY_DEVICE_TO_HOST",0,"Agent 4","Agent 0",24,1057963498099125,1057963498200446

projects/rocprofiler-sdk/source/docs/data/pc_sampling_host_trap.csv

@@ -0,0 +1,80 @@
+"Sample_Timestamp","Exec_Mask","Dispatch_Id","Instruction","Instruction_Comment","Correlation_Id"
+3464444413017201,65535,1,"s_endpgm","",1
+3464444413017201,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413018481,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413018481,65535,1,"s_endpgm","",1
+3464444413018481,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413018481,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413018481,65535,1,"s_endpgm","",1
+3464444413018481,65535,1,"s_endpgm","",1
+3464444413019601,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413019761,65535,1,"s_load_dword s8, s[4:5], 0x24","",1
+3464444413019761,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413019761,65535,1,"s_endpgm","",1
+3464444413019761,65535,1,"s_load_dword s8, s[4:5], 0x24","",1
+3464444413019761,65535,1,"s_endpgm","",1
+3464444413019761,65535,1,"s_endpgm","",1
+3464444413020881,65535,1,"s_endpgm","",1
+3464444413020881,65535,1,"s_endpgm","",1
+3464444413020881,65535,1,"s_endpgm","",1
+3464444413020881,65535,1,"s_waitcnt lgkmcnt(0)","",1
+3464444413020881,65535,1,"v_addc_co_u32_e32 v5, vcc, v1, v5, vcc","",1
+3464444413020881,65535,1,"s_endpgm","",1
+3464444413020881,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413020881,65535,1,"s_endpgm","",1
+3464444413020881,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413021041,65535,1,"s_endpgm","",1
+3464444413020881,65535,1,"v_bfe_u32 v0, v0, 10, 10","",1
+3464444413021041,65535,1,"s_endpgm","",1
+3464444413021041,65535,1,"s_endpgm","",1
+3464444413021041,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413021041,65535,1,"s_endpgm","",1
+3464444413021041,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413021041,65535,1,"s_endpgm","",1
+3464444413022001,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413022001,65535,1,"s_endpgm","",1
+3464444413022001,65535,1,"s_endpgm","",1
+3464444413022001,65535,1,"s_endpgm","",1
+3464444413022001,65535,1,"s_endpgm","",1
+3464444413022001,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413022001,65535,1,"s_endpgm","",1
+3464444413022001,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413022001,65535,1,"s_waitcnt lgkmcnt(0)","",1
+3464444413022161,65535,1,"s_endpgm","",1
+3464444413022161,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413022161,65535,1,"s_endpgm","",1
+3464444413022161,65535,1,"s_load_dword s8, s[4:5], 0x24","",1
+3464444413022161,65535,1,"global_store_dword v[0:1], v3, off","",1
+3464444413022161,65535,1,"s_endpgm","",1
+3464444413022161,65535,1,"s_endpgm","",1
+3464444413022161,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413022161,65535,1,"s_endpgm","",1
+3464444413022161,65535,1,"s_endpgm","",1
+3464444413022161,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413022161,65535,1,"s_endpgm","",1
+3464444413022321,65535,1,"s_load_dwordx4 s[0:3], s[4:5], 0x0","",1
+3464444413022161,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413022321,65535,1,"s_endpgm","",1
+3464444413022161,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413023281,65535,1,"s_endpgm","",1
+3464444413023281,65535,1,"s_endpgm","",1
+3464444413023281,65535,1,"v_ashrrev_i32_e32 v1, 31, v0","",1
+3464444413024561,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413023281,65535,1,"s_endpgm","",1
+3464444413024561,65535,1,"s_endpgm","",1
+3464444413023761,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413026321,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413024401,65535,1,"global_store_dword v[0:1], v3, off","",1
+3464444413027121,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413025041,65535,1,"v_add_co_u32_e32 v0, vcc, s0, v0","",1
+3464444413027761,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413025361,65535,1,"s_endpgm","",1
+3464444413027601,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413026321,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413028401,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413026481,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413028881,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413026641,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413028401,65535,1,"s_load_dword s8, s[4:5], 0x24","",1
+3464444413027281,65535,1,"s_waitcnt vmcnt(0)","",1
+3464444413029681,65535,1,"s_endpgm","",1

projects/rocprofiler-sdk/source/docs/data/pc_sampling_host_trap_debug.csv

@@ -0,0 +1,22 @@
+"Sample_Timestamp","Exec_Mask","Dispatch_Id","Instruction","Instruction_Comment","Correlation_Id"
+54155306462675,65535,1,"s_waitcnt lgkmcnt(0)","/opt/rocm/include/hip/amd_detail/amd_hip_runtime.h:275",1
+54155306462715,65535,1,"s_waitcnt vmcnt(0)","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:44",1
+54155306462755,65535,1,"s_endpgm","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:45",1
+54155306462755,65535,1,"s_endpgm","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:45",1
+54155306462955,65535,1,"s_endpgm","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:45",1
+54155306463035,65535,1,"s_waitcnt vmcnt(0)","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:44",1
+54155306463235,65535,1,"s_waitcnt vmcnt(0)","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:44",1
+54155306463315,65535,1,"s_waitcnt vmcnt(0)","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:44",1
+54155306463515,65535,1,"s_endpgm","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:45",1
+54155306463755,65535,1,"s_waitcnt vmcnt(0)","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:44",1
+54155306463875,65535,1,"s_waitcnt vmcnt(0)","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:44",1
+54155306464075,65535,1,"v_mov_b32_e32 v2, s4","/opt/rocm/include/hip/amd_detail/amd_hip_runtime.h:275",1
+54155306464155,65535,1,"s_waitcnt vmcnt(0)","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:44",1
+54155306464155,65535,1,"s_waitcnt vmcnt(0)","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:44",1
+54155306464275,65535,1,"s_endpgm","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:45",1
+54155306464395,65535,1,"s_waitcnt vmcnt(0)","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:44",1
+54155306464515,65535,1,"s_waitcnt lgkmcnt(0)","/opt/rocm/include/hip/amd_detail/amd_hip_runtime.h:275",1
+54155306464555,65535,1,"s_waitcnt vmcnt(0)","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:44",1
+54155306464595,65535,1,"s_waitcnt vmcnt(0)","/opt/rocm-6.4.0/share/hip/samples/2_Cookbook/0_MatrixTranspose/MatrixTranspose.cpp:44",1
+54155306464595,65535,1,"v_mov_b32_e32 v2, s6","/opt/rocm/include/hip/amd_detail/amd_hip_runtime.h:275",1
+54155306464595,65535,1,"s_waitcnt lgkmcnt(0)","/opt/rocm/include/hip/amd_detail/amd_hip_runtime.h:275",1

projects/rocprofiler-sdk/source/docs/data/pc_sampling_stochastic_debug.csv

@@ -0,0 +1,98 @@
+"Sample_Timestamp","Exec_Mask","Dispatch_Id","Instruction","Instruction_Comment","Correlation_Id","Wave_Issued_Instruction","Instruction_Type","Stall_Reason","Wave_Count"
+390705261841337,18446744073709551615,24,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",24,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390705261924637,18446744073709551615,29,"v_max_i32_e32 v1, v2, v0","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:77",29,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",6
+390705694732429,18446744073709551615,53,"v_mad_u64_u32 v[0:1], s[2:3], v0, s2, v[2:3]","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:80",53,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",6
+390705694744189,18446744073709551615,54,"v_lshl_add_u64 v[0:1], s[4:5], 0, v[0:1]","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",54,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",4
+390705694769549,18446744073709551615,56,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",56,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",6
+390705694772089,18446744073709551615,56,"s_waitcnt lgkmcnt(0)","/usr/include/hip/amd_detail/amd_hip_runtime.h:275",56,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390705694810449,18446744073709551615,58,"v_cmp_gt_i32_e32 vcc, s2, v1","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:94",58,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",3
+390705694820489,18446744073709551615,59,"s_waitcnt vmcnt(1)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",59,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390705694840850,18446744073709551615,60,"s_and_b32 s5, s4, 0xffff","/usr/include/hip/amd_detail/amd_hip_runtime.h:275",60,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_SCALAR","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",5
+390705694856630,18446744073709551615,61,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",61,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706112944694,18446744073709551615,65,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",65,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",7
+390706112965404,18446744073709551615,66,"global_store_dword v[0:1], v2, off","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",66,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_ALU_DEPENDENCY",3
+390706112966284,18446744073709551615,66,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",66,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",6
+390706112966644,18446744073709551615,66,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",66,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",3
+390706112967404,18446744073709551615,66,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",66,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706112971414,18446744073709551615,66,"s_load_dwordx4 s[4:7], s[0:1], 0x0","/usr/include/hip/amd_detail/amd_hip_runtime.h:275",66,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_SCALAR","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",5
+390706112984885,18446744073709551615,67,"s_waitcnt vmcnt(1)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",67,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706112988655,18446744073709551615,67,"s_waitcnt vmcnt(1)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",67,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706113000775,18446744073709551615,68,"v_add_u32_e32 v0, s3, v0","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:128",68,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",5
+390706113004375,18446744073709551615,68,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",68,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706113053815,18446744073709551615,69,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",69,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",7
+390706113059125,18446744073709551615,69,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",69,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",6
+390706113080805,18446744073709551615,70,"s_load_dwordx4 s[4:7], s[0:1], 0x0","/usr/include/hip/amd_detail/amd_hip_runtime.h:275",70,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_SCALAR","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",3
+390706113097725,18446744073709551615,71,"s_waitcnt vmcnt(1)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",71,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",3
+390706113101805,18446744073709551615,71,"s_waitcnt vmcnt(1)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",71,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706113111775,18446744073709551615,72,"v_sub_f32_e32 v4, v2, v3","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",72,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",5
+390706113115735,18446744073709551615,72,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",72,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706113134725,18446744073709551615,73,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",73,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",7
+390706113147605,18446744073709551615,74,"s_waitcnt lgkmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:97",74,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706113149485,18446744073709551615,74,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",74,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706113153735,18446744073709551615,74,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",74,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706113179326,18446744073709551615,76,"s_waitcnt lgkmcnt(0)","/usr/include/hip/amd_detail/amd_hip_runtime.h:275",76,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",2
+390706113184086,18446744073709551615,76,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",76,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706113184406,18446744073709551615,76,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",76,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706113206736,18446744073709551615,77,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",77,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",10
+390706113209216,18446744073709551615,77,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",77,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",11
+390706113220016,18446744073709551615,78,"s_load_dword s4, s[0:1], 0x2c","/usr/include/hip/amd_detail/amd_hip_runtime.h:275",78,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_NO_INSTRUCTION_AVAILABLE",1
+390706113221566,18446744073709551615,78,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",78,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706113227816,18446744073709551615,78,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",78,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706113234976,18446744073709551615,79,"s_waitcnt vmcnt(1)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",79,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706113235016,18446744073709551615,79,"s_load_dwordx2 s[0:1], s[0:1], 0x10","/usr/include/hip/amd_detail/amd_hip_runtime.h:275",79,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_SCALAR","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",3
+390706113236806,18446744073709551615,79,"s_and_saveexec_b64 s[2:3], vcc","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:113",79,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_ALU_DEPENDENCY",3
+390706113250926,18446744073709551615,80,"s_waitcnt lgkmcnt(0)","/usr/include/hip/amd_detail/amd_hip_runtime.h:275",80,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",1
+390706113253456,18446744073709551615,80,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",80,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706113255496,18446744073709551615,80,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",80,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",6
+390706113257566,18446744073709551615,80,"v_add_f32_e32 v2, 1.0, v2","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",80,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",4
+390706113270176,18446744073709551615,81,"s_waitcnt lgkmcnt(0)","/usr/include/hip/amd_detail/amd_hip_runtime.h:275",81,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",3
+390706113278256,18446744073709551615,81,"s_load_dword s2, s[0:1], 0x18","/usr/include/hip/amd_detail/amd_hip_runtime.h:275",81,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_SCALAR","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",8
+390706113292776,18446744073709551615,82,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",82,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",3
+390706113301126,18446744073709551615,83,"s_waitcnt lgkmcnt(0)","/usr/include/hip/amd_detail/amd_hip_runtime.h:275",83,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",1
+390706113301606,18446744073709551615,83,"s_and_saveexec_b64 s[2:3], vcc","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:113",83,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_ALU_DEPENDENCY",3
+390706113303846,18446744073709551615,83,"s_and_saveexec_b64 s[2:3], vcc","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:113",83,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_ALU_DEPENDENCY",3
+390706113305086,18446744073709551615,83,"v_lshlrev_b64 v[0:1], 2, v[0:1]","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",83,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",3
+390706113317256,18446744073709551615,84,"v_div_fmas_f32 v3, v3, v6, v7","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",84,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",5
+390706113318166,18446744073709551615,84,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",84,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",6
+390706113336687,18446744073709551615,85,"global_load_dword v2, v[2:3], off","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",85,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_ALU_DEPENDENCY",11
+390706113351087,18446744073709551615,86,"s_mul_i32 s2, s2, s5","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:93",86,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_SCALAR","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",3
+390706113352487,18446744073709551615,86,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",86,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706113369607,18446744073709551615,87,"s_waitcnt vmcnt(1)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",87,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",6
+390706113373647,18446744073709551615,87,"s_waitcnt vmcnt(1)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",87,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706113387017,18446744073709551615,88,"s_waitcnt lgkmcnt(0)","/usr/include/hip/amd_detail/amd_hip_runtime.h:275",88,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",1
+390706113390207,18446744073709551615,88,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",88,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706113408977,18446744073709551615,89,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",89,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706113409057,18446744073709551615,89,"v_add_f32_e32 v2, v2, v3","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",89,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",10
+390706113411607,18446744073709551615,89,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",89,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",9
+390706113411737,18446744073709551615,89,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",89,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",7
+390706113412777,18446744073709551615,89,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",89,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",7
+390706113415847,18446744073709551615,89,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",89,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",9
+390706113424217,18446744073709551615,90,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",90,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706113443127,18446744073709551615,91,"v_add_f32_e32 v2, -1.0, v2","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",91,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",2
+390706113444857,18446744073709551615,91,"v_add_f32_e32 v3, -1.0, v3","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",91,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",3
+390706113459367,18446744073709551615,92,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",92,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",6
+390706113459767,18446744073709551615,92,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",92,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",6
+390706113462927,18446744073709551615,92,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",92,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706113480097,18446744073709551615,93,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",93,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",15
+390706113484087,18446744073709551615,93,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",93,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",7
+390706113496167,18446744073709551615,93,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",93,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",6
+390706113500167,18446744073709551615,93,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",93,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",9
+390706113506057,18446744073709551615,93,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",93,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",14
+390706113506327,18446744073709551615,93,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",93,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",6
+390706113508577,18446744073709551615,93,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",93,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",17
+390706113522058,18446744073709551615,93,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",93,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",15
+390706113561378,18446744073709551615,94,"s_waitcnt lgkmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:97",94,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",3
+390706113573138,18446744073709551615,95,"s_waitcnt vmcnt(1)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",95,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706526501642,18446744073709551615,112,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",112,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",6
+390706526582893,18446744073709551615,117,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:82",117,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",8
+390706526594683,18446744073709551615,118,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",118,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706526629813,18446744073709551615,120,"s_waitcnt lgkmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:131",120,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706526629803,18446744073709551615,120,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",120,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706526633683,18446744073709551615,120,"v_mul_f32_e32 v7, v3, v6","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",120,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",4
+390706526634933,18446744073709551615,120,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",120,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706526665053,18446744073709551615,122,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",122,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",4
+390706526677283,18446744073709551615,123,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",123,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",6
+390706526695733,18446744073709551615,124,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:133",124,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706526809694,18446744073709551615,126,"v_and_b32_e32 v2, 0x7fffffff, v2","/opt/rocm-6.4.0/lib/llvm/lib/clang/19/include/__clang_hip_math.h:427",126,1,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",5
+390706526810014,18446744073709551615,126,"s_waitcnt vmcnt(0)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:99",126,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5
+390706526821284,18446744073709551615,127,"s_waitcnt vmcnt(1)","/home/vlaindic/git/rocprofiler-sdk-internal/tests/bin/vector-operations/vector-ops.cpp:116",127,0,"ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_NO_INST","ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_WAITCNT",5

projects/rocprofiler-sdk/source/docs/data/python_bindings.csv

@@ -0,0 +1,7 @@
+"Domain","Function","Process_Id","Thread_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
+"MARKER_CORE_API","MatrixTranspose: rows=4, cols=5",15964,15964,1,1392141764711512,1392141764711512
+"MARKER_CORE_API","generate_matrix(rows=4, cols=5)",15964,15964,4,1392141765500646,1392141765523276
+"MARKER_CORE_API","transpose(nrows=4, ncols=5)",15964,15964,7,1392141765527536,1392141765531786
+"MARKER_CORE_API","matrix_transpose",15964,15964,6,1392141765525156,1392141765532696
+"MARKER_CORE_API","run(rows=4, cols=5)",15964,15964,3,1392141765498106,1392141765534186
+"MARKER_CORE_API","main",15964,15964,2,1392141765494795,1392141765574506

projects/rocprofiler-sdk/source/docs/data/rccl_trace.csv

@@ -0,0 +1,22 @@
+"Domain","Function","Process_Id","Thread_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
+"RCCL_API","ncclGetVersion",1834151,1834151,416,18413845573432,18413845577374
+"RCCL_API","ncclGetUniqueId",1834151,1834151,1116,18413961300878,18413963267869
+"RCCL_API","ncclGetUniqueId",1834151,1834151,1481,18414166449182,18414166720831
+"RCCL_API","ncclGroupStart",1834151,1834151,1482,18414166723772,18414166726834
+"RCCL_API","ncclGroupEnd",1834151,1834151,1490,18414166823575,18414380520973
+"RCCL_API","ncclCommInitAll",1834151,1834151,1477,18414166402665,18414380522536
+"RCCL_API","ncclCommGetAsyncError",1834151,1834151,89098,18414380660695,18414380661652
+"RCCL_API","ncclAllReduce",1834151,1834151,89097,18414380653860,18414380693574
+"RCCL_API","ncclCommGetAsyncError",1834151,1834151,89108,18414380694631,18414380694659
+"RCCL_API","ncclAllReduce",1834151,1834151,89107,18414380694212,18414380704722
+"RCCL_API","ncclCommGetAsyncError",1834151,1834151,89117,18414380706650,18414380706677
+"RCCL_API","ncclAllReduce",1834151,1834151,89116,18414380705574,18414380715055
+"RCCL_API","ncclCommGetAsyncError",1834151,1834151,89126,18414380715749,18414380715774
+"RCCL_API","ncclAllReduce",1834151,1834151,89125,18414380715463,18414380723944
+"RCCL_API","ncclCommGetAsyncError",1834151,1834151,89135,18414380724688,18414380724715
+"RCCL_API","ncclAllReduce",1834151,1834151,89134,18414380724395,18414380732209
+"RCCL_API","ncclCommGetAsyncError",1834151,1834151,89154,18414380746383,18414380746411
+"RCCL_API","ncclCommGetAsyncError",1834151,1834151,89157,18414380749863,18414380749889
+"RCCL_API","ncclCommGetAsyncError",1834151,1834151,89160,18414380751671,18414380751696
+"RCCL_API","ncclCommGetAsyncError",1834151,1834151,89163,18414380753326,18414380753353
+"RCCL_API","ncclCommGetAsyncError",1834151,1834151,89166,18414380755128,18414380755154

projects/rocprofiler-sdk/source/docs/data/rocdecode_api_trace.csv

@@ -0,0 +1,7 @@
+"Domain","Function","Process_Id","Thread_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
+"ROCDECODE_API","rocDecCreateVideoParser",41688,41688,583,615449881677279,615449882001583
+"ROCDECODE_API","rocDecGetDecoderCaps",41688,41688,584,615449882016054,615449882163756
+"ROCDECODE_API","rocDecGetDecoderCaps",41688,41688,588,615449886038750,615449886050880
+"ROCDECODE_API","rocDecCreateDecoder",41688,41688,591,615449886084210,615450756910310
+"ROCDECODE_API","rocDecDecodeFrame",41688,41688,595,615450757036042,615450767147413
+"ROCDECODE_API","rocDecGetDecodeStatus",41688,41688,812,615450836779385,615450836779575

projects/rocprofiler-sdk/source/docs/data/rocjpeg_api_trace.csv

@@ -0,0 +1,5 @@
+"Domain","Function","Process_Id","Thread_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
+"ROCJPEG_API","rocJpegCreate",41884,41884,105,1286306029650499,1286306248201233
+"ROCJPEG_API","rocJpegStreamCreate",41884,41884,502,1286306248250747,1286306248268715
+"ROCJPEG_API","rocJpegStreamParse",41884,41884,503,1286306248421385,1286306248680757
+"ROCJPEG_API","rocJpegGetImageInfo",41884,41884,504,1286306248684203,1286306248686556

projects/rocprofiler-sdk/source/docs/data/rocm-smi.txt

@@ -0,0 +1,11 @@
+============================================ ROCm System Management Interface ============================================
+====================================================== Concise Info ======================================================
+Device  Node  IDs              Temp        Power     Partitions          SCLK    MCLK     Fan  Perf  PwrCap  VRAM%  GPU%
+        (DID,     GUID)  (Junction)  (Socket)  (Mem, Compute, ID)
+==========================================================================================================================
+0       4     0x74a0,   50375  48.0°C      110.0W    NPS1, SPX, 0        98Mhz   1300Mhz  0%   auto  550.0W  0%     0%
+1       5     0x74a0,   20890  53.0°C      113.0W    NPS1, SPX, 0        99Mhz   1200Mhz  0%   auto  550.0W  0%     0%
+2       6     0x74a0,   44670  52.0°C      125.0W    NPS1, SPX, 0        100Mhz  1300Mhz  0%   auto  550.0W  0%     0%
+3       7     0x74a0,   15139  47.0°C      115.0W    NPS1, SPX, 0        100Mhz  1300Mhz  0%   auto  550.0W  0%     0%
+==========================================================================================================================
+================================================== End of ROCm SMI Log ===================================================

projects/rocprofiler-sdk/source/docs/data/rocpd-to-csv.csv

@@ -0,0 +1,14 @@
+"Guid","Domain","Function","Process_Id","Thread_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
+"0000ddb5-8903-7903-b269-cd8d3745bb8a","HIP_COMPILER_API_EXT","__hipRegisterFatBinary",137,137,1,3719662243949943,3719662243977763
+"0000ddb5-8903-7903-b269-cd8d3745bb8a","HIP_COMPILER_API_EXT","__hipRegisterFunction",137,137,2,3719662243992513,3719662244013373
+"0000ddb5-8903-7903-b269-cd8d3745bb8a","HIP_RUNTIME_API_EXT","hipGetDevicePropertiesR0600",137,137,3,3719662244489885,3719662300657772
+"0000ddb5-8903-7903-b269-cd8d3745bb8a","HIP_RUNTIME_API_EXT","hipMalloc",137,137,4,3719662301007843,3719662301139564
+"0000ddb5-8903-7903-b269-cd8d3745bb8a","HIP_RUNTIME_API_EXT","hipMalloc",137,137,5,3719662301140994,3719662301221024
+"0000ddb5-8903-7903-b269-cd8d3745bb8a","HIP_RUNTIME_API_EXT","hipMemcpy",137,137,6,3719662301228614,3719662416709451
+"0000ddb5-8903-7903-b269-cd8d3745bb8a","HIP_RUNTIME_API_EXT","hipMemcpy",137,137,7,3719662416720791,3719662416728291
+"0000ddb5-8903-7903-b269-cd8d3745bb8a","HIP_COMPILER_API_EXT","__hipPushCallConfiguration",137,137,8,3719662416731301,3719662416733001
+"0000ddb5-8903-7903-b269-cd8d3745bb8a","HIP_COMPILER_API_EXT","__hipPopCallConfiguration",137,137,9,3719662416734631,3719662416735421
+"0000ddb5-8903-7903-b269-cd8d3745bb8a","HIP_RUNTIME_API_EXT","hipLaunchKernel",137,137,10,3719662416752501,3719662417325443
+"0000ddb5-8903-7903-b269-cd8d3745bb8a","HIP_RUNTIME_API_EXT","hipMemcpy",137,137,11,3719662417327973,3719662418667169
+"0000ddb5-8903-7903-b269-cd8d3745bb8a","HIP_RUNTIME_API_EXT","hipFree",137,137,12,3719662428427823,3719662428488874
+"0000ddb5-8903-7903-b269-cd8d3745bb8a","HIP_RUNTIME_API_EXT","hipFree",137,137,13,3719662428491354,3719662428514084

projects/rocprofiler-sdk/source/docs/data/scratch_memory_trace.csv

@@ -0,0 +1,3 @@
+"Kind","Operation","Agent_Id","Queue_Id","Thread_Id","Alloc_Flags","Start_Timestamp","End_Timestamp"
+"SCRATCH_MEMORY","SCRATCH_MEMORY_ALLOC","Agent 4",1,113,0,1124926523146168,1124926554133606
+"SCRATCH_MEMORY","SCRATCH_MEMORY_ALLOC","Agent 4",1,113,0,1124926554522025,1124927132642186

projects/rocprofiler-sdk/source/docs/data/summary.txt

@@ -0,0 +1,154 @@
+
+ROCPROFV3 HSA_API SUMMARY:
+
+|                   NAME                    |    DOMAIN    |      CALLS      | DURATION (nsec) | AVERAGE (nsec)  | PERCENT (INC) |   MIN (nsec)    |   MAX (nsec)    |     STDDEV      |
+|-------------------------------------------|--------------|-----------------|-----------------|-----------------|---------------|-----------------|-----------------|-----------------|
+| hsa_queue_create                          | HSA_API      |               4 |       280077621 |       7.002e+07 |     75.372632 |        55026812 |       113288760 |       2.885e+07 |
+| hsa_amd_memory_async_copy_on_engine       | HSA_API      |              24 |        55617052 |       2.317e+06 |     14.967292 |            7580 |        55195188 |       1.126e+07 |
+| hsa_amd_memory_pool_allocate              | HSA_API      |              67 |        26428438 |       3.945e+05 |      7.112246 |            1510 |          857592 |       1.782e+05 |
+| hsa_amd_memory_pool_free                  | HSA_API      |              72 |         5176173 |       7.189e+04 |      1.392977 |             290 |          170374 |       3.903e+04 |
+| hsa_executable_freeze                     | HSA_API      |               2 |          964125 |       4.821e+05 |      0.259459 |          437471 |          526654 |       6.306e+04 |
+| hsa_signal_wait_scacquire                 | HSA_API      |              26 |          853122 |       3.281e+04 |      0.229587 |            2530 |          100782 |       3.394e+04 |
+| hsa_executable_load_agent_code_object     | HSA_API      |               2 |          616175 |       3.081e+05 |      0.165821 |          254476 |          361699 |       7.582e+04 |
+| hsa_amd_agents_allow_access               | HSA_API      |              35 |          430680 |       1.231e+04 |      0.115902 |            4830 |           55182 |       9.939e+03 |
+| hsa_signal_store_screlease                | HSA_API      |              56 |          381491 |       6.812e+03 |      0.102664 |            1560 |           41831 |       7.895e+03 |
+| hsa_signal_create                         | HSA_API      |             107 |          160889 |       1.504e+03 |      0.043297 |              80 |            5650 |       1.475e+03 |
+| hsa_code_object_reader_create_from_memory | HSA_API      |               2 |          151314 |       7.566e+04 |      0.040721 |           32121 |          119193 |       6.157e+04 |
+| hsa_signal_load_relaxed                   | HSA_API      |            1296 |          137626 |       1.062e+02 |      0.037037 |              20 |            2930 |       2.712e+02 |
+| hsa_signal_destroy                        | HSA_API      |             618 |          111224 |       1.800e+02 |      0.029932 |              40 |            1540 |       2.429e+02 |
+| hsa_agent_get_info                        | HSA_API      |              65 |           77472 |       1.192e+03 |      0.020849 |              30 |           47121 |       6.341e+03 |
+| hsa_amd_signal_create                     | HSA_API      |             512 |           61290 |       1.197e+02 |      0.016494 |              40 |             930 |       1.559e+02 |
+| hsa_amd_signal_async_handler              | HSA_API      |              24 |           52641 |       2.193e+03 |      0.014166 |            1180 |            4020 |       9.252e+02 |
+| hsa_executable_iterate_symbols            | HSA_API      |              14 |           52521 |       3.752e+03 |      0.014134 |            2740 |            6940 |       1.105e+03 |
+| hsa_amd_memory_copy_engine_status         | HSA_API      |              18 |           47370 |       2.632e+03 |      0.012748 |             260 |            7990 |       2.274e+03 |
+| hsa_iterate_agents                        | HSA_API      |               1 |           41391 |       4.139e+04 |      0.011139 |           41391 |           41391 |       0.000e+00 |
+| hsa_executable_create_alt                 | HSA_API      |               2 |           40470 |       2.024e+04 |      0.010891 |            7530 |           32940 |       1.797e+04 |
+| hsa_isa_get_info_alt                      | HSA_API      |               2 |           30391 |       1.520e+04 |      0.008179 |            2490 |           27901 |       1.797e+04 |
+| hsa_signal_silent_store_relaxed           | HSA_API      |              48 |           24920 |       5.192e+02 |      0.006706 |              20 |            4570 |       7.120e+02 |
+| hsa_amd_agent_iterate_memory_pools        | HSA_API      |               5 |           20221 |       4.044e+03 |      0.005442 |            2561 |            8600 |       2.574e+03 |
+| hsa_queue_add_write_index_screlease       | HSA_API      |              56 |            7270 |       1.298e+02 |      0.001956 |              30 |            2310 |       3.471e+02 |
+| hsa_amd_profiling_set_profiler_enabled    | HSA_API      |               4 |            5600 |       1.400e+03 |      0.001507 |            1370 |            1470 |       4.690e+01 |
+| hsa_executable_symbol_get_info            | HSA_API      |             152 |            5470 |       3.599e+01 |      0.001472 |              30 |             340 |       3.563e+01 |
+| hsa_queue_load_read_index_relaxed         | HSA_API      |              56 |            4560 |       8.143e+01 |      0.001227 |              20 |            1310 |       1.863e+02 |
+| hsa_executable_get_symbol_by_name         | HSA_API      |              14 |            4500 |       3.214e+02 |      0.001211 |             110 |            1510 |       4.732e+02 |
+| hsa_queue_load_read_index_scacquire       | HSA_API      |              56 |            3040 |       5.429e+01 |      0.000818 |              30 |             690 |       8.705e+01 |
+| hsa_amd_memory_pool_get_info              | HSA_API      |              43 |            1770 |       4.116e+01 |      0.000476 |              30 |             270 |       3.640e+01 |
+| hsa_system_get_info                       | HSA_API      |               4 |            1750 |       4.375e+02 |      0.000471 |              40 |             830 |       3.544e+02 |
+| hsa_amd_agent_memory_pool_get_info        | HSA_API      |              13 |            1140 |       8.769e+01 |      0.000307 |              30 |             640 |       1.664e+02 |
+| hsa_agent_iterate_isas                    | HSA_API      |               1 |             700 |       7.000e+02 |      0.000188 |             700 |             700 |       0.000e+00 |
+| hsa_system_get_major_extension_table      | HSA_API      |               1 |             190 |       1.900e+02 |      0.000051 |             190 |             190 |       0.000e+00 |
+
+
+ROCPROFV3 HIP_API SUMMARY:
+
+|                   NAME                   |    DOMAIN    |      CALLS      | DURATION (nsec) | AVERAGE (nsec)  | PERCENT (INC) |   MIN (nsec)    |   MAX (nsec)    |     STDDEV      |
+|------------------------------------------|--------------|-----------------|-----------------|-----------------|---------------|-----------------|-----------------|-----------------|
+| hipStreamCreateWithFlags                 | HIP_API      |               8 |       406507215 |       5.081e+07 |     71.307804 |          735979 |       233800881 |       7.889e+07 |
+| hipGetDeviceCount                        | HIP_API      |               1 |        76707894 |       7.671e+07 |     13.455780 |        76707894 |        76707894 |       0.000e+00 |
+| hipMemcpyAsync                           | HIP_API      |              24 |        56109444 |       2.338e+06 |      9.842485 |           11640 |        55299811 |       1.128e+07 |
+| hipHostMalloc                            | HIP_API      |              24 |        13007523 |       5.420e+05 |      2.281726 |          416631 |          866382 |       1.206e+05 |
+| hipMallocAsync                           | HIP_API      |              24 |         7304847 |       3.044e+05 |      1.281386 |          275397 |          353719 |       2.207e+04 |
+| hipHostFree                              | HIP_API      |              24 |         2786484 |       1.161e+05 |      0.488793 |           72242 |          221646 |       4.606e+04 |
+| hipStreamDestroy                         | HIP_API      |               8 |         2137924 |       2.672e+05 |      0.375026 |          221596 |          377469 |       5.489e+04 |
+| hipLaunchKernel                          | HIP_API      |              32 |         2080214 |       6.501e+04 |      0.364902 |            8850 |         1608721 |       2.819e+05 |
+| hipFree                                  | HIP_API      |              24 |         1572948 |       6.554e+04 |      0.275920 |            2130 |          186994 |       4.815e+04 |
+| hipStreamSynchronize                     | HIP_API      |              24 |         1452706 |       6.053e+04 |      0.254828 |           20810 |          135803 |       3.469e+04 |
+| __hipRegisterFunction                    | HIP_API      |               4 |          294207 |       7.355e+04 |      0.051609 |             210 |          291807 |       1.455e+05 |
+| hipDeviceSynchronize                     | HIP_API      |               4 |           50663 |       1.267e+04 |      0.008887 |             510 |           23621 |       9.554e+03 |
+| __hipRegisterFatBinary                   | HIP_API      |               1 |           43811 |       4.381e+04 |      0.007685 |           43811 |           43811 |       0.000e+00 |
+| __hipPushCallConfiguration               | HIP_API      |              32 |            6250 |       1.953e+02 |      0.001096 |              60 |            3640 |       6.308e+02 |
+| __hipPopCallConfiguration                | HIP_API      |              32 |            4780 |       1.494e+02 |      0.000838 |              60 |            2520 |       4.340e+02 |
+| hipGetLastError                          | HIP_API      |              32 |            4471 |       1.397e+02 |      0.000784 |              60 |            2381 |       4.092e+02 |
+| hipSetDevice                             | HIP_API      |               1 |            2570 |       2.570e+03 |      0.000451 |            2570 |            2570 |       0.000e+00 |
+
+
+ROCPROFV3 KERNEL_DISPATCH SUMMARY:
+
+|                                   NAME                                    |     DOMAIN      |      CALLS      | DURATION (nsec) | AVERAGE (nsec)  | PERCENT (INC) |   MIN (nsec)    |   MAX (nsec)    |     STDDEV      |
+|---------------------------------------------------------------------------|-----------------|-----------------|-----------------|-----------------|---------------|-----------------|-----------------|-----------------|
+| void addition_kernel<float>(float*, float const*, float const*, int, int) | KERNEL_DISPATCH |               8 |          184324 |       2.304e+04 |     40.681542 |           11200 |           98802 |       3.062e+04 |
+| divide_kernel(float*, float const*, float const*, int, int)               | KERNEL_DISPATCH |               8 |           94482 |       1.181e+04 |     20.852811 |           10240 |           13520 |       1.061e+03 |
+| multiply_kernel(float*, float const*, float const*, int, int)             | KERNEL_DISPATCH |               8 |           91763 |       1.147e+04 |     20.252709 |            9800 |           12800 |       9.417e+02 |
+| subtract_kernel(float*, float const*, float const*, int, int)             | KERNEL_DISPATCH |               8 |           82521 |       1.032e+04 |     18.212938 |            8320 |           12920 |       1.436e+03 |
+
+
+ROCPROFV3 MEMORY_COPY SUMMARY:
+
+|                   NAME                   |    DOMAIN    |      CALLS      | DURATION (nsec) | AVERAGE (nsec)  | PERCENT (INC) |   MIN (nsec)    |   MAX (nsec)    |     STDDEV      |
+|------------------------------------------|--------------|-----------------|-----------------|-----------------|---------------|-----------------|-----------------|-----------------|
+| MEMORY_COPY_HOST_TO_DEVICE               | MEMORY_COPY  |              16 |         3691929 |       2.307e+05 |     85.494053 |           74842 |          284487 |       6.265e+04 |
+| MEMORY_COPY_DEVICE_TO_HOST               | MEMORY_COPY  |               8 |          626417 |       7.830e+04 |     14.505947 |           74842 |           98603 |       8.207e+03 |
+
+
+ROCPROFV3 MEMORY_ALLOCATION SUMMARY:
+
+|                   NAME                   |      DOMAIN       |      CALLS      | DURATION (nsec) | AVERAGE (nsec)  | PERCENT (INC) |   MIN (nsec)    |   MAX (nsec)    |     STDDEV      |
+|------------------------------------------|-------------------|-----------------|-----------------|-----------------|---------------|-----------------|-----------------|-----------------|
+| MEMORY_ALLOCATION_ALLOCATE               | MEMORY_ALLOCATION |              67 |        26314096 |       3.927e+05 |     83.661617 |             950 |          856812 |       1.785e+05 |
+| MEMORY_ALLOCATION_FREE                   | MEMORY_ALLOCATION |              72 |         5138913 |       7.137e+04 |     16.338383 |              20 |          166234 |       3.882e+04 |
+
+
+ROCPROFV3 SUMMARY:
+
+|                                   NAME                                    |      DOMAIN       |      CALLS      | DURATION (nsec) | AVERAGE (nsec)  | PERCENT (INC) |   MIN (nsec)    |   MAX (nsec)    |     STDDEV      |
+|---------------------------------------------------------------------------|-------------------|-----------------|-----------------|-----------------|---------------|-----------------|-----------------|-----------------|
+| hipStreamCreateWithFlags                                                  | HIP_API           |               8 |       406507215 |       5.081e+07 |     41.569873 |          735979 |       233800881 |       7.889e+07 |
+| hsa_queue_create                                                          | HSA_API           |               4 |       280077621 |       7.002e+07 |     28.641044 |        55026812 |       113288760 |       2.885e+07 |
+| hipGetDeviceCount                                                         | HIP_API           |               1 |        76707894 |       7.671e+07 |      7.844233 |        76707894 |        76707894 |       0.000e+00 |
+| hipMemcpyAsync                                                            | HIP_API           |              24 |        56109444 |       2.338e+06 |      5.737813 |           11640 |        55299811 |       1.128e+07 |
+| hsa_amd_memory_async_copy_on_engine                                       | HSA_API           |              24 |        55617052 |       2.317e+06 |      5.687461 |            7580 |        55195188 |       1.126e+07 |
+| hsa_amd_memory_pool_allocate                                              | HSA_API           |              67 |        26428438 |       3.945e+05 |      2.702601 |            1510 |          857592 |       1.782e+05 |
+| MEMORY_ALLOCATION_ALLOCATE                                                | MEMORY_ALLOCATION |              67 |        26314096 |       3.927e+05 |      2.690908 |             950 |          856812 |       1.785e+05 |
+| hipHostMalloc                                                             | HIP_API           |              24 |        13007523 |       5.420e+05 |      1.330164 |          416631 |          866382 |       1.206e+05 |
+| hipMallocAsync                                                            | HIP_API           |              24 |         7304847 |       3.044e+05 |      0.747002 |          275397 |          353719 |       2.207e+04 |
+| hsa_amd_memory_pool_free                                                  | HSA_API           |              72 |         5176173 |       7.189e+04 |      0.529321 |             290 |          170374 |       3.903e+04 |
+| MEMORY_ALLOCATION_FREE                                                    | MEMORY_ALLOCATION |              72 |         5138913 |       7.137e+04 |      0.525511 |              20 |          166234 |       3.882e+04 |
+| MEMORY_COPY_HOST_TO_DEVICE                                                | MEMORY_COPY       |              16 |         3691929 |       2.307e+05 |      0.377541 |           74842 |          284487 |       6.265e+04 |
+| hipHostFree                                                               | HIP_API           |              24 |         2786484 |       1.161e+05 |      0.284949 |           72242 |          221646 |       4.606e+04 |
+| hipStreamDestroy                                                          | HIP_API           |               8 |         2137924 |       2.672e+05 |      0.218626 |          221596 |          377469 |       5.489e+04 |
+| hipLaunchKernel                                                           | HIP_API           |              32 |         2080214 |       6.501e+04 |      0.212725 |            8850 |         1608721 |       2.819e+05 |
+| hipFree                                                                   | HIP_API           |              24 |         1572948 |       6.554e+04 |      0.160851 |            2130 |          186994 |       4.815e+04 |
+| hipStreamSynchronize                                                      | HIP_API           |              24 |         1452706 |       6.053e+04 |      0.148555 |           20810 |          135803 |       3.469e+04 |
+| hsa_executable_freeze                                                     | HSA_API           |               2 |          964125 |       4.821e+05 |      0.098592 |          437471 |          526654 |       6.306e+04 |
+| hsa_signal_wait_scacquire                                                 | HSA_API           |              26 |          853122 |       3.281e+04 |      0.087241 |            2530 |          100782 |       3.394e+04 |
+| MEMORY_COPY_DEVICE_TO_HOST                                                | MEMORY_COPY       |               8 |          626417 |       7.830e+04 |      0.064058 |           74842 |           98603 |       8.207e+03 |
+| hsa_executable_load_agent_code_object                                     | HSA_API           |               2 |          616175 |       3.081e+05 |      0.063011 |          254476 |          361699 |       7.582e+04 |
+| hsa_amd_agents_allow_access                                               | HSA_API           |              35 |          430680 |       1.231e+04 |      0.044042 |            4830 |           55182 |       9.939e+03 |
+| hsa_signal_store_screlease                                                | HSA_API           |              56 |          381491 |       6.812e+03 |      0.039012 |            1560 |           41831 |       7.895e+03 |
+| __hipRegisterFunction                                                     | HIP_API           |               4 |          294207 |       7.355e+04 |      0.030086 |             210 |          291807 |       1.455e+05 |
+| void addition_kernel<float>(float*, float const*, float const*, int, int) | KERNEL_DISPATCH   |               8 |          184324 |       2.304e+04 |      0.018849 |           11200 |           98802 |       3.062e+04 |
+| hsa_signal_create                                                         | HSA_API           |             107 |          160889 |       1.504e+03 |      0.016453 |              80 |            5650 |       1.475e+03 |
+| hsa_code_object_reader_create_from_memory                                 | HSA_API           |               2 |          151314 |       7.566e+04 |      0.015474 |           32121 |          119193 |       6.157e+04 |
+| hsa_signal_load_relaxed                                                   | HSA_API           |            1296 |          137626 |       1.062e+02 |      0.014074 |              20 |            2930 |       2.712e+02 |
+| hsa_signal_destroy                                                        | HSA_API           |             618 |          111224 |       1.800e+02 |      0.011374 |              40 |            1540 |       2.429e+02 |
+| divide_kernel(float*, float const*, float const*, int, int)               | KERNEL_DISPATCH   |               8 |           94482 |       1.181e+04 |      0.009662 |           10240 |           13520 |       1.061e+03 |
+| multiply_kernel(float*, float const*, float const*, int, int)             | KERNEL_DISPATCH   |               8 |           91763 |       1.147e+04 |      0.009384 |            9800 |           12800 |       9.417e+02 |
+| subtract_kernel(float*, float const*, float const*, int, int)             | KERNEL_DISPATCH   |               8 |           82521 |       1.032e+04 |      0.008439 |            8320 |           12920 |       1.436e+03 |
+| hsa_agent_get_info                                                        | HSA_API           |              65 |           77472 |       1.192e+03 |      0.007922 |              30 |           47121 |       6.341e+03 |
+| hsa_amd_signal_create                                                     | HSA_API           |             512 |           61290 |       1.197e+02 |      0.006268 |              40 |             930 |       1.559e+02 |
+| hsa_amd_signal_async_handler                                              | HSA_API           |              24 |           52641 |       2.193e+03 |      0.005383 |            1180 |            4020 |       9.252e+02 |
+| hsa_executable_iterate_symbols                                            | HSA_API           |              14 |           52521 |       3.752e+03 |      0.005371 |            2740 |            6940 |       1.105e+03 |
+| hipDeviceSynchronize                                                      | HIP_API           |               4 |           50663 |       1.267e+04 |      0.005181 |             510 |           23621 |       9.554e+03 |
+| hsa_amd_memory_copy_engine_status                                         | HSA_API           |              18 |           47370 |       2.632e+03 |      0.004844 |             260 |            7990 |       2.274e+03 |
+| __hipRegisterFatBinary                                                    | HIP_API           |               1 |           43811 |       4.381e+04 |      0.004480 |           43811 |           43811 |       0.000e+00 |
+| hsa_iterate_agents                                                        | HSA_API           |               1 |           41391 |       4.139e+04 |      0.004233 |           41391 |           41391 |       0.000e+00 |
+| hsa_executable_create_alt                                                 | HSA_API           |               2 |           40470 |       2.024e+04 |      0.004139 |            7530 |           32940 |       1.797e+04 |
+| hsa_isa_get_info_alt                                                      | HSA_API           |               2 |           30391 |       1.520e+04 |      0.003108 |            2490 |           27901 |       1.797e+04 |
+| hsa_signal_silent_store_relaxed                                           | HSA_API           |              48 |           24920 |       5.192e+02 |      0.002548 |              20 |            4570 |       7.120e+02 |
+| hsa_amd_agent_iterate_memory_pools                                        | HSA_API           |               5 |           20221 |       4.044e+03 |      0.002068 |            2561 |            8600 |       2.574e+03 |
+| hsa_queue_add_write_index_screlease                                       | HSA_API           |              56 |            7270 |       1.298e+02 |      0.000743 |              30 |            2310 |       3.471e+02 |
+| __hipPushCallConfiguration                                                | HIP_API           |              32 |            6250 |       1.953e+02 |      0.000639 |              60 |            3640 |       6.308e+02 |
+| hsa_amd_profiling_set_profiler_enabled                                    | HSA_API           |               4 |            5600 |       1.400e+03 |      0.000573 |            1370 |            1470 |       4.690e+01 |
+| hsa_executable_symbol_get_info                                            | HSA_API           |             152 |            5470 |       3.599e+01 |      0.000559 |              30 |             340 |       3.563e+01 |
+| __hipPopCallConfiguration                                                 | HIP_API           |              32 |            4780 |       1.494e+02 |      0.000489 |              60 |            2520 |       4.340e+02 |
+| hsa_queue_load_read_index_relaxed                                         | HSA_API           |              56 |            4560 |       8.143e+01 |      0.000466 |              20 |            1310 |       1.863e+02 |
+| hsa_executable_get_symbol_by_name                                         | HSA_API           |              14 |            4500 |       3.214e+02 |      0.000460 |             110 |            1510 |       4.732e+02 |
+| hipGetLastError                                                           | HIP_API           |              32 |            4471 |       1.397e+02 |      0.000457 |              60 |            2381 |       4.092e+02 |
+| hsa_queue_load_read_index_scacquire                                       | HSA_API           |              56 |            3040 |       5.429e+01 |      0.000311 |              30 |             690 |       8.705e+01 |
+| hipSetDevice                                                              | HIP_API           |               1 |            2570 |       2.570e+03 |      0.000263 |            2570 |            2570 |       0.000e+00 |
+| hsa_amd_memory_pool_get_info                                              | HSA_API           |              43 |            1770 |       4.116e+01 |      0.000181 |              30 |             270 |       3.640e+01 |
+| hsa_system_get_info                                                       | HSA_API           |               4 |            1750 |       4.375e+02 |      0.000179 |              40 |             830 |       3.544e+02 |
+| hsa_amd_agent_memory_pool_get_info                                        | HSA_API           |              13 |            1140 |       8.769e+01 |      0.000117 |              30 |             640 |       1.664e+02 |
+| hsa_agent_iterate_isas                                                    | HSA_API           |               1 |             700 |       7.000e+02 |      0.000072 |             700 |             700 |       0.000e+00 |
+| hsa_system_get_major_extension_table                                      | HSA_API           |               1 |             190 |       1.900e+02 |      0.000019 |             190 |             190 |       0.000e+00 |
+

projects/rocprofiler-sdk/source/docs/environment.yml

@@ -0,0 +1,129 @@
+name: rocprofiler-docs
+channels:
+  - conda-forge
+
+dependencies:
+  - _libgcc_mutex=0.1=conda_forge
+  - _openmp_mutex=4.5=2_gnu
+  - alabaster=0.7.13=pyhd8ed1ab_0
+  - atk-1.0=2.38.0=hd4edc92_1
+  - babel=2.12.1=pyhd8ed1ab_1
+  - brotli-python=1.1.0=py311hb755f60_0
+  - bzip2=1.0.8=h7f98852_4
+  - c-ares=1.19.1=hd590300_0
+  - ca-certificates=2023.7.22=hbcca054_0
+  - cairo=1.16.0=h0c91306_1017
+  - certifi=2023.7.22=pyhd8ed1ab_0
+  - charset-normalizer=3.2.0=pyhd8ed1ab_0
+  - cmake=3.27.4=hcfe8598_4
+  - colorama=0.4.6=pyhd8ed1ab_0
+  - commonmark=0.9.1=py_0
+  - doxygen=1.9.8=h661eb56_0
+  - expat=2.5.0=hcb278e6_1
+  - font-ttf-dejavu-sans-mono=2.37=hab24e00_0
+  - font-ttf-inconsolata=3.000=h77eed37_0
+  - font-ttf-source-code-pro=2.038=h77eed37_0
+  - font-ttf-ubuntu=0.83=hab24e00_0
+  - fontconfig=2.14.2=h14ed4e7_0
+  - fonts-conda-ecosystem=1=0
+  - fonts-conda-forge=1=0
+  - freetype=2.12.1=hca18f0e_1
+  - fribidi=1.0.10=h36c2ea0_0
+  - future=0.18.3=pyhd8ed1ab_0
+  - gdk-pixbuf=2.42.10=h6b639ba_2
+  - gettext=0.21.1=h27087fc_0
+  - giflib=5.2.1=h0b41bf4_3
+  - graphite2=1.3.13=h58526e2_1001
+  - graphviz=8.1.0=h28d9a01_0
+  - gtk2=2.24.33=h90689f9_2
+  - gts=0.7.6=h977cf35_4
+  - harfbuzz=8.2.0=h3d44ed6_0
+  - icu=73.2=h59595ed_0
+  - idna=3.4=pyhd8ed1ab_0
+  - imagesize=1.4.1=pyhd8ed1ab_0
+  - importlib-metadata=6.8.0=pyha770c72_0
+  - jinja2=3.1.2=pyhd8ed1ab_1
+  - keyutils=1.6.1=h166bdaf_0
+  - krb5=1.21.2=h659d440_0
+  - ld_impl_linux-64=2.40=h41732ed_0
+  - lerc=4.0.0=h27087fc_0
+  - libcurl=8.2.1=hca28451_0
+  - libdeflate=1.18=h0b41bf4_0
+  - libedit=3.1.20191231=he28a2e2_2
+  - libev=4.33=h516909a_1
+  - libexpat=2.5.0=hcb278e6_1
+  - libffi=3.4.2=h7f98852_5
+  - libgcc-ng=13.2.0=h807b86a_0
+  - libgd=2.3.3=h74d50f4_7
+  - libglib=2.78.0=hebfc3b9_0
+  - libgomp=13.2.0=h807b86a_0
+  - libiconv=1.17=h166bdaf_0
+  - libjpeg-turbo=2.1.5.1=h0b41bf4_0
+  - libnghttp2=1.52.0=h61bc06f_0
+  - libnsl=2.0.0=h7f98852_0
+  - libpng=1.6.39=h753d276_0
+  - librsvg=2.56.3=h98fae49_0
+  - libsqlite=3.43.0=h2797004_0
+  - libssh2=1.11.0=h0841786_0
+  - libstdcxx-ng=13.2.0=h7e041cc_0
+  - libtiff=4.5.1=h8b53f26_1
+  - libtool=2.4.7=h27087fc_0
+  - libuuid=2.38.1=h0b41bf4_0
+  - libuv=1.46.0=hd590300_0
+  - libwebp=1.3.1=hbf2b3c1_0
+  - libwebp-base=1.3.1=hd590300_0
+  - libxcb=1.15=h0b41bf4_0
+  - libxml2=2.11.5=h232c23b_1
+  - libzlib=1.2.13=hd590300_5
+  - markdown=3.4.4=pyhd8ed1ab_0
+  - markupsafe=2.1.3=py311h459d7ec_0
+  - ncurses=6.4=hcb278e6_0
+  - openssl=3.1.2=hd590300_0
+  - packaging=23.1=pyhd8ed1ab_0
+  - pango=1.50.14=ha41ecd1_2
+  - pcre2=10.40=hc3806b6_0
+  - pip=23.2.1=pyhd8ed1ab_0
+  - pixman=0.40.0=h36c2ea0_0
+  - pthread-stubs=0.4=h36c2ea0_1001
+  - pygments=2.16.1=pyhd8ed1ab_0
+  - pysocks=1.7.1=pyha2e5f31_6
+  - python=3.11.5=hab00c5b_0_cpython
+  - python_abi=3.11=3_cp311
+  - pytz=2023.3.post1=pyhd8ed1ab_0
+  - readline=8.2=h8228510_1
+  - recommonmark=0.7.1=pyhd8ed1ab_0
+  - requests=2.31.0=pyhd8ed1ab_0
+  - rhash=1.4.4=hd590300_0
+  - setuptools=68.1.2=pyhd8ed1ab_0
+  - snowballstemmer=2.2.0=pyhd8ed1ab_0
+  - sphinx=7.2.5=pyhd8ed1ab_0
+  - sphinx-markdown-tables=0.0.17=pyh6c4a22f_0
+  - sphinx_rtd_theme=1.3.0=pyha770c72_0
+  - sphinxcontrib-applehelp=1.0.7=pyhd8ed1ab_0
+  - sphinxcontrib-devhelp=1.0.5=pyhd8ed1ab_0
+  - sphinxcontrib-htmlhelp=2.0.4=pyhd8ed1ab_0
+  - sphinxcontrib-jquery=4.1=pyhd8ed1ab_0
+  - sphinxcontrib-jsmath=1.0.1=pyhd8ed1ab_0
+  - sphinxcontrib-qthelp=1.0.6=pyhd8ed1ab_0
+  - sphinxcontrib-serializinghtml=1.1.9=pyhd8ed1ab_0
+  - tk=8.6.12=h27826a3_0
+  - tzdata=2023c=h71feb2d_0
+  - urllib3=2.0.4=pyhd8ed1ab_0
+  - wheel=0.41.2=pyhd8ed1ab_0
+  - xorg-kbproto=1.0.7=h7f98852_1002
+  - xorg-libice=1.1.1=hd590300_0
+  - xorg-libsm=1.2.4=h7391055_0
+  - xorg-libx11=1.8.6=h8ee46fc_0
+  - xorg-libxau=1.0.11=hd590300_0
+  - xorg-libxdmcp=1.1.3=h7f98852_0
+  - xorg-libxext=1.3.4=h0b41bf4_2
+  - xorg-libxrender=0.9.11=hd590300_0
+  - xorg-renderproto=0.11.1=h7f98852_1002
+  - xorg-xextproto=7.3.0=h0b41bf4_1003
+  - xorg-xproto=7.0.31=h7f98852_1007
+  - xz=5.2.6=h166bdaf_0
+  - zipp=3.16.2=pyhd8ed1ab_0
+  - zlib=1.2.13=hd590300_5
+  - zstd=1.5.5=hfc55251_0
+  - pip:
+      - -r ./sphinx/requirements.txt

projects/rocprofiler-sdk/source/docs/generate-doxyfile.cmake

@@ -0,0 +1,22 @@
+if(NOT DEFINED SOURCE_DIR)
+    message(FATAL_ERROR "Please define SOURCE_DIR")
+endif()
+
+get_filename_component(SOURCE_DIR "${SOURCE_DIR}" ABSOLUTE)
+
+find_program(DOT_EXECUTABLE NAMES dot)
+
+if(NOT DOT_EXECUTABLE)
+    message(FATAL_ERROR "Please install dot and/or specify DOT_EXECUTABLE")
+endif()
+
+file(READ "${SOURCE_DIR}/VERSION" FULL_VERSION_STRING LIMIT_COUNT 1)
+string(REGEX REPLACE "(\n|\r)" "" FULL_VERSION_STRING "${FULL_VERSION_STRING}")
+string(REGEX REPLACE "([0-9]+)\\.([0-9]+)\\.([0-9]+)(.*)" "\\1.\\2.\\3"
+                     ROCPROFILER_VERSION "${FULL_VERSION_STRING}")
+
+configure_file(${SOURCE_DIR}/source/docs/rocprofiler-sdk.dox.in
+               ${SOURCE_DIR}/source/docs/rocprofiler-sdk.dox @ONLY)
+
+configure_file(${SOURCE_DIR}/source/docs/rocprofiler-sdk-roctx.dox.in
+               ${SOURCE_DIR}/source/docs/rocprofiler-sdk-roctx.dox @ONLY)

projects/rocprofiler-sdk/source/docs/how-to/samples.rst

@@ -0,0 +1,49 @@
+.. meta::
+    :description: "ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software."
+    :keywords: "ROCprofiler-SDK, ROCProfiler-SDK samples"
+
+.. _rocprofiler-sdk-samples:
+
+ROCprofiler-SDK samples
+========================
+
+The samples are provided to help you see the profiler in action.
+
+Finding samples
+---------------
+
+The ROCm installation provides sample programs and ``rocprofv3`` tool.
+
+- Sample programs are installed here:
+
+.. code-block:: bash
+    
+    /opt/rocm/share/rocprofiler-sdk/samples
+
+- ``rocprofv3`` tool is installed here:
+
+.. code-block:: bash
+    
+    /opt/rocm/bin
+
+Building Samples
+----------------
+
+To build samples from any directory, run:
+
+.. code-block:: bash
+
+    cmake -B build-rocprofiler-sdk-samples /opt/rocm/share/rocprofiler-sdk/samples -DCMAKE_PREFIX_PATH=/opt/rocm
+    cmake --build build-rocprofiler-sdk-samples --target all --parallel 8
+
+
+Running samples
+---------------
+
+To run the built samples, ``cd`` into the ``build-rocprofiler-sdk-samples`` directory and run:
+
+.. code-block:: bash
+    
+    ctest -V
+
+The `-V` option enables verbose output, providing detailed information about the test execution.

projects/rocprofiler-sdk/source/docs/how-to/using-pc-sampling.rst

@@ -0,0 +1,357 @@
+.. meta::
+  :description: Documentation of the usage of pc-sampling with rocprofv3 command-line tool
+  :keywords: Sampling PC, Sampling program counter, rocprofv3, rocprofv3 tool usage, Using rocprofv3, ROCprofiler-SDK command line tool, PC sampling
+
+.. _using-pc-sampling:
+
+==================
+Using PC sampling
+==================
+
+PC (Program Counter) sampling service for GPU profiling is a profiling technique to periodically sample the program counter during GPU kernel execution. PC sampling helps in understanding code execution patterns and identifying hotspot(s).
+
+Here are the benefits of using PC sampling:
+
+- Identify performance bottlenecks
+- Understand kernel execution behavior
+- Analyze code coverage
+- Find heavily executed code paths
+
+To try out the PC sampling feature, you can use the command-line tool ``rocprofv3`` or the ROCprofiler-SDK library on `ROCm 6.4` or later.
+
+.. note::
+  PC sampling is ONLY supported on AMD GPUs with architectures gfx90a and later.
+
+PC sampling availability and configuration
+===========================================
+
+To check if the GPU supports PC sampling, use:
+
+.. code-block:: bash
+
+  rocprofv3 -L
+
+Or
+
+.. code-block:: bash
+
+  rocprofv3 --list-avail
+
+The output lists if ``rocprofv3`` supports PC sampling on the GPU and the supported configuration.
+
+.. code-block:: bash
+
+    GPU:0
+    NAME:gfx90a
+    configs:
+       Method              :host_trap
+       Unit                :time
+       Min_Interval        :1
+       Max_Interval        :18446744073709551615
+       Flags               :none
+
+The preceding output shows that the GPU supports PC sampling with the ``ROCPROFILER_PC_SAMPLING_METHOD_HOST_TRAP`` method and the ``ROCPROFILER_PC_SAMPLING_UNIT_TIME`` unit. The minimum and maximum intervals are also displayed.
+
+.. note::
+   Important firmware fixes to host-trap and stochastic PC-sampling for AMD Instinct MI300X have been made in ROCm 7.0.
+   To ensure that you have the latest fixes, check if you have the correct firmware versions installed:
+
+   For host-trap PC-sampling on MI300X: PSP TOS Firmware >= version 00.36.02.59 or 0x00360259
+   For stochastic PC-sampling on MI300X  as described in the following section: MEC Firmware feature version: 50, firmware version >= 0x0000001a
+
+To check the firmware versions, use:
+
+.. code-block:: bash
+
+  # To check PSP TOS Firmware: 
+  sudo cat /sys/kernel/debug/dri/0/amdgpu_firmware_info | grep SOS
+
+  # To check MEC Firmware:
+  sudo cat /sys/kernel/debug/dri/1/amdgpu_firmware_info | grep MEC
+
+Based on the available PC-sampling configurations, use the following command to profile the application using PC-sampling:
+
+.. code-block:: bash
+
+  rocprofv3 --pc-sampling-beta-enabled --pc-sampling-method host_trap --pc-sampling-unit time --pc-sampling-interval 1 --output-format csv -- <application_path>
+
+The preceding command enables PC sampling with the ``host_trap`` method, ``time`` unit, and an interval of ``1`` μs (microsecond). Replace ``<application_path>`` with the path to the application you want to profile.
+
+This generates two files, ``agent_info.csv`` and ``pc_sampling_host_trap.csv``. Both files are prefixed with the process ID.
+
+Here are the contents of ``pc_sampling_host_trap.csv`` file generated for MatrixTranspose sample application:
+
+.. csv-table:: PC sampling host trap
+   :file: /data/pc_sampling_host_trap.csv
+   :widths: 20,10,10,10,10,20
+   :header-rows: 1
+
+
+For description of the fields in the output file, see :ref:`pc-sampling-fields`.
+
+If you find the ``Instruction_Comment`` field in the output file to be empty, populate this field by compiling your application with debug symbols.
+Enabling debug symbols while compiling the application maps back to the source line. This helps in understanding the code execution pattern and hotspots.
+
+.. csv-table:: PC sampling host trap with debug symbols
+   :file: /data/pc_sampling_host_trap_debug.csv
+   :widths: 20,10,10,10,10,20
+   :header-rows: 1
+
+
+The preceding output shows the ``Instruction_Comment`` field populated with the source-line information.
+
+.. _pc-sampling-fields:
+
+PC sampling fields
+===================
+
+Here are the fields in the output file generated by PC sampling:
+
+- ``Sample_Timestamp``: Timestamp when sample is generated
+- ``Exec_Mask``: Active SIMD lanes when sampled
+- ``Dispatch_Id``: Originating kernel dispatch ID
+- ``Instruction``: Assembly instruction such as ``s_load_dword s8, s[1:2], 0x10``
+- ``Instruction_Comment``: Instruction comment that maps back to the source-line if debug symbols were enabled when application was compiled
+- ``Correlation_Id``: API launch call ID that matches dispatch ID
+
+ To dump samples in a more comprehensive format, use JSON through ``--output-format json``:
+
+.. code-block:: bash
+
+  rocprofv3 --pc-sampling-beta-enabled --pc-sampling-method host_trap --pc-sampling-unit time --pc-sampling-interval 1 --output-format json -- <application_path>
+
+The preceding command generates a JSON file with the comprehensive output. Here is a trimmed down output with multiple records:
+
+.. code-block:: text
+
+  {
+    "pc_sample_host_trap": [
+      {
+        "record": {
+          "hw_id": {
+            "chiplet": 0,
+            "wave_id": 0,
+            "simd_id": 2,
+            "pipe_id": 0,
+            "cu_or_wgp_id": 1,
+            "shader_array_id": 0,
+            "shader_engine_id": 2,
+            "workgroup_id": 0,
+            "vm_id": 3,
+            "queue_id": 2,
+            "microengine_id": 1
+          },
+          "pc": {
+            "code_object_id": 1,
+            "code_object_offset": 20228
+          },
+          "exec_mask": 18446744073709551615,
+          "timestamp": 51040126667689,
+          "dispatch_id": 1,
+          "corr_id": {
+            "internal": 1,
+            "external": 0
+          },
+          "wrkgrp_id": {
+            "x": 182,
+            "y": 0,
+            "z": 0
+          },
+          "wave_in_grp": 1
+        },
+        "inst_index": 0
+      },
+      {
+        "record": {
+          "hw_id": {
+            "chiplet": 0,
+            "wave_id": 0,
+            "simd_id": 2,
+            "pipe_id": 0,
+            "cu_or_wgp_id": 0,
+            "shader_array_id": 0,
+            "shader_engine_id": 2,
+            "workgroup_id": 0,
+            "vm_id": 3,
+            "queue_id": 2,
+            "microengine_id": 1
+          },
+          "pc": {
+            "code_object_id": 1,
+            "code_object_offset": 20236
+          },
+          "exec_mask": 18446744073709551615,
+          "timestamp": 51040126667689,
+          "dispatch_id": 1,
+          "corr_id": {
+            "internal": 1,
+            "external": 0
+          },
+          "wrkgrp_id": {
+            "x": 158,
+            "y": 0,
+            "z": 0
+          },
+          "wave_in_grp": 2
+        },
+        "inst_index": 1
+      }
+    ]
+  }
+
+For description of the fields in the JSON output, see :ref:`output-file-fields`.
+
+An Arbitrary Host-Trap PC Sampling Skid
+===============================================
+
+Host-Trap PC sampling is a software-based technique that utilizes a background kernel thread
+to periodically interrupt running waves in order to capture the program counter (PC).
+This method is effective for gathering performance data without requiring specialized hardware
+to snapshot the waves. However, it has limitations due to the potential delay between 
+when a wave receives an interrupt and when it processes the interrupt to capture the PC.
+This delay can lead to a sampling skid, where the PC samples may be attributed to instructions
+that are up to two instructions away from the actual source of latency.
+This results in a non-precise intra-kernel sampling method.
+
+When analyzing an application profile generated by host-trap PC sampling,
+developers should consider not only the reported most costly instruction but
+also the instructions immediately preceding or following it.
+If the costly instruction is near a branch instruction, it is important 
+to also consider the instruction targeted by the branch and the one immediately following it.
+
+To address the limitations of host-trap sampling, the hardware-based stochastic PC sampling method
+has been developed. This method provides precise intra-kernel sampling with zero sampling skid,
+offering more accurate performance insights.
+
+It is important to note that the skid issue inherent in host-trap PC sampling will not be resolved
+in its current form. Therefore, users are encouraged to adopt stochastic PC sampling,
+starting with the GFX942 architecture, to achieve more precise performance profiling.
+
+Hardware-Based (Stochastic) PC Sampling Method
+===============================================
+
+The new ``ROCPROFILER_PC_SAMPLING_METHOD_STOCHASTIC`` has been introduced for gfx942 architecture.
+It employs a specific hardware for probing waves actively running on GPU.
+Beside information already provided with ``ROCPROFILER_PC_SAMPLING_METHOD_HOST_TRAP`` useful for determining hot-spots within the kernel,
+it delivers additional information that tells whether a sampled wave issued an instruction represented with particular PC.
+If not, it provides the reason for not issuing the instruction (stall reason).
+This type of information is particularly useful for understanding stalls during the kernel execution.
+
+To use this method on gfx942, we recommend listing available PC sampling configurations to verify if the latest ROCm stack is installed
+on the system by running:
+
+.. code-block:: bash
+
+  rocprofv3 -L
+
+Output similar to the following indicates that the ``ROCPROFILER_PC_SAMPLING_METHOD_STOCHASTIC`` method is available:
+
+.. code-block:: bash
+
+    GPU:1
+    NAME:gfx942
+    configs:
+       Method              :stochastic
+       Unit                :cycle
+       Min_Interval        :256
+       Max_Interval        :2147483648
+       Flags               :interval pow2
+
+Please note that on gfx942, `ROCPROFILER_PC_SAMPLING_METHOD_STOCHASTIC` requires intervals to be specified in cycles, whose values are powers of 2
+
+To profile a gfx942 accelerated application with ``ROCPROFILER_PC_SAMPLING_METHOD_STOCHASTIC`` PC sampling, one can use the following command:
+
+.. code-block:: bash
+
+  rocprofv3 --pc-sampling-beta-enabled --pc-sampling-method stochastic --pc-sampling-unit cycles --pc-sampling-interval 1048576 --output-format csv, json -- <application_path>
+
+The previous command serializes samples in both CSV and JSON output formats in the ``pc_sampling_stochastic.csv`` and ``out_results.json`` files, respectively.
+
+Comparing the ``pc_sampling_stochastic.csv`` to ``pc_sampling_host_trap`` from previous section, one can notice that the ``ROCPROFILER_PC_SAMPLING_METHOD_STOCHASTIC`` method
+generates additional fields:
+- ``Wave_Issued_Instruction``: Indicates whether the wave issued an instruction (value 1) represented with particular PC or not (value 0)
+- ``Instruction_Type``: If the value of ``Wave_Issued_Instruction`` is 1, this fields indicates the type of the issued instruction. Otherwise, this fields irrelevant.
+- ``Stall_Reason``: If the value of ``Wave_Issued_Instruction`` is 0, this fields indicates the reason for not issuing the instruction (stall reason). Otherwise, this field is irrelevant.
+- ``Wave_Count``: Total number of waves actively running on a compute unit when the sample was generated.
+
+.. csv-table:: PC sampling stochastic with debug symbols
+   :file: /data/pc_sampling_stochastic_debug.csv
+   :widths: 20,10,10,10,10,20,10,20,20,10
+   :header-rows: 1
+
+Similarly, ``ROCPROFILER_PC_SAMPLING_METHOD_STOCHASTIC`` method delivers additional information to every sample in the JSON output.
+The following snippet shows one sample from ``out_results.json`` file.
+
+.. code-block:: text
+
+  {
+    "record": {
+      "flags": {
+        "has_mem_cnt": 0
+      },
+      "hw_id": {
+        "chiplet": 4,
+        "wave_id": 0,
+        "simd_id": 2,
+        "pipe_id": 3,
+        "cu_or_wgp_id": 1,
+        "shader_array_id": 0,
+        "shader_engine_id": 3,
+        "workgroup_id": 0,
+        "vm_id": 3,
+        "queue_id": 2,
+        "microengine_id": 1
+      },
+      "pc": {
+        "code_object_id": 2,
+        "code_object_offset": 13880
+      },
+      "exec_mask": 18446744073709551615,
+      "timestamp": 390705261924637,
+      "dispatch_id": 29,
+      "corr_id": {
+        "internal": 29,
+        "external": 0
+      },
+      "wrkgrp_id": {
+        "x": 9,
+        "y": 489,
+        "z": 0
+      },
+      "wave_in_grp": 0,
+      "wave_issued": 1,
+      "inst_type": "ROCPROFILER_PC_SAMPLING_INSTRUCTION_TYPE_VALU",
+      "wave_cnt": 6,
+      "snapshot": {
+        "stall_reason": "ROCPROFILER_PC_SAMPLING_INSTRUCTION_NOT_ISSUED_REASON_OTHER_WAIT",
+        "dual_issue_valu": 0,
+        "arb_state_issue_valu": 1,
+        "arb_state_issue_matrix": 0,
+        "arb_state_issue_lds": 0,
+        "arb_state_issue_lds_direct": 0,
+        "arb_state_issue_scalar": 0,
+        "arb_state_issue_vmem_tex": 0,
+        "arb_state_issue_flat": 0,
+        "arb_state_issue_exp": 0,
+        "arb_state_issue_misc": 0,
+        "arb_state_issue_brmsg": 0,
+        "arb_state_stall_valu": 0,
+        "arb_state_stall_matrix": 0,
+        "arb_state_stall_lds": 0,
+        "arb_state_stall_lds_direct": 0,
+        "arb_state_stall_scalar": 0,
+        "arb_state_stall_vmem_tex": 0,
+        "arb_state_stall_flat": 0,
+        "arb_state_stall_exp": 0,
+        "arb_state_stall_misc": 0,
+        "arb_state_stall_brmsg": 0
+      }
+    },
+    "inst_index": 1
+  },
+
+Fields starting with ``arb_state_`` are of particular interest as they indicate the state of the arbiter at the time of sampling.
+Namely, ``arb_state_issue_`` fields indicate what type of instructions arbiter issued at the time of sampling.
+On the other hand, ``arb_state_stall_`` fields indicate what type of instructions were stalled at the time of sampling.
+This information is useful for understanding how many instructions per cycle (IPC) are issued.
+

projects/rocprofiler-sdk/source/docs/how-to/using-rocpd-output-format.rst

@@ -0,0 +1,193 @@
+.. meta::
+    :description: "ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software."
+    :keywords: "ROCprofiler-SDK, ROCProfiler-SDK output formats, rocpd, SQLite3, CSV, JSON, PFTrace, OTF2"
+
+.. _using-rocpd-output-format:
+
+=========================
+Using rocpd Output Format
+=========================
+
+``rocprofv3`` supports the following output formats:
+
+- **rocpd** (SQLite3 Database, Default)
+- **CSV**
+- **JSON** (Custom format for programmatic analysis only)
+- **PFTrace** (Perfetto trace for visualization with Perfetto)
+- **OTF2** (Open Trace Format for visualization with compatible third-party tools)
+
+The ``rocpd`` output format is the default for ``rocprofv3``. It stores profiling results in a SQLite3 database, providing a structured and efficient way to analyze and post-process profiling data. This format allows users to query and manipulate profiling data using SQL, making it easy to extract specific information or perform complex analyses.
+
+Features
+++++++++
+
+- **Rich Data Model**: Stores all collected profiling data, including traces, counters, and metadata, in a single `.db` (SQLite3) file.
+- **Programmatic Access**: Can be queried using standard SQL tools or libraries (e.g., `sqlite3` CLI, Python's `sqlite3` module).
+- **Post-Processing**: Enables advanced analysis and visualization using custom scripts or third-party tools that support SQLite3.
+
+Generating rocpd Output
++++++++++++++++++++++++
+
+To generate output in rocpd format, simply use:
+
+.. code-block:: bash
+
+   rocprofv3 --hip-trace -- <application>
+
+Or use the ``--output-format`` option with ``rocpd``:
+
+.. code-block:: bash
+
+   rocprofv3 --hip-trace --output-format rocpd -- <application>
+
+The output will be saved as ``%hostname%/%pid%_results.db``, where ``%hostname%`` is the name of the host machine and ``%pid%`` is the process ID of the application being profiled.
+
+Converting rocpd to Other Formats
++++++++++++++++++++++++++++++++++
+
+The ``rocpd`` output format can be converted to other formats for further analysis or visualization.  
+First, ensure the ``rocpd`` Python module is available in your environment:
+
+.. code-block:: bash
+
+   export PYTHONPATH=<install-path>/lib/pythonX.Y/site-packages:$PYTHONPATH
+
+where ``<install-path>`` is the ROCm installation path (usually ``/opt/rocm-<major.minor.patch>``), and ``X.Y`` is your Python version.
+
+Once the ``rocpd`` module is available, use the ``rocpd convert`` command to convert the output to other formats.
+
+Convert to CSV format:
+
+.. code-block:: bash
+
+   python3 -m rocpd convert -i <input-file>.db --output-format csv
+
+The converted CSV will be saved as ``rocpd-output-data/out_hip_api_trace.csv`` in the current working directory.
+
+Convert to OTF2 format:
+
+.. code-block:: bash
+
+   python3 -m rocpd convert -i <input-file>.db --output-format otf2
+
+Convert to PFTrace format:
+
+.. code-block:: bash
+
+   python3 -m rocpd convert -i <input-file>.db --output-format pftrace
+
+rocpd convert Command-Line Options
+++++++++++++++++++++++++++++++++++
+
+.. code-block:: none
+
+   usage: rocpd convert [-h] -i INPUT [INPUT ...] -f {csv,pftrace,otf2} [{csv,pftrace,otf2} ...]
+                        [-o OUTPUT_FILE] [-d OUTPUT_PATH] [--kernel-rename]
+                        [--agent-index-value {absolute,relative,type-relative}]
+                        [--perfetto-backend {inprocess,system}]
+                        [--perfetto-buffer-fill-policy {discard,ring_buffer}]
+                        [--perfetto-buffer-size KB] [--perfetto-shmem-size-hint KB]
+                        [--group-by-queue]
+                        [--start START | --start-marker START_MARKER]
+                        [--end END | --end-marker END_MARKER]
+                        [--inclusive INCLUSIVE]
+
+Options
+-------
+
+**Required Arguments:**
+
+- ``-i INPUT [INPUT ...]``, ``--input INPUT [INPUT ...]``  
+  Input path and filename to one or more database(s), separated by spaces.
+
+- ``-f {csv,pftrace,otf2} [{csv,pftrace,otf2} ...]``, ``--output-format {csv,pftrace,otf2} [{csv,pftrace,otf2} ...]``  
+  Specify one or more output formats. Supported: ``csv``, ``pftrace``, ``otf2``.
+
+**I/O Options:**
+
+- ``-o OUTPUT_FILE``, ``--output-file OUTPUT_FILE``  
+  Sets the base output file name (default: ``out``).
+
+- ``-d OUTPUT_PATH``, ``--output-path OUTPUT_PATH``  
+  Sets the output directory (default: ``./rocpd-output-data``).
+
+**Kernel Naming Options:**
+
+- ``--kernel-rename``  
+  Use ROCTx marker names instead of kernel names.
+
+**Generic Options:**
+
+- ``--agent-index-value {absolute,relative,type-relative}``  
+  Device identification format in output:
+  
+  - ``absolute``: Uses node_id (e.g., Agent-0, Agent-2, Agent-4), ignoring cgroups.
+  - ``relative``: Uses logical_node_id (e.g., Agent-0, Agent-1, Agent-2), considering cgroups. *(Default)*
+  - ``type-relative``: Uses logical_node_type_id (e.g., CPU-0, GPU-0, GPU-1), numbering resets for each device type.
+
+**Perfetto Trace (pftrace) Options:**
+
+- ``--perfetto-backend {inprocess,system}``  
+  Perfetto data collection backend. ``system`` mode requires running ``traced`` and ``perfetto`` daemons (default: ``inprocess``).
+
+- ``--perfetto-buffer-fill-policy {discard,ring_buffer}``  
+  Policy for handling new records when buffer is full (default: ``discard``).
+
+- ``--perfetto-buffer-size KB``  
+  Buffer size for perfetto output in KB (default: 1 GB).
+
+- ``--perfetto-shmem-size-hint KB``  
+  Perfetto shared memory size hint in KB (default: 64 KB).
+
+- ``--group-by-queue``  
+  Display HIP streams that kernels and memory copy operations are submitted to, rather than HSA queues.
+
+**Time Window Options:**
+
+- ``--start START``  
+  Start time as percentage or nanoseconds from trace file (e.g., ``50%`` or ``781470909013049``).
+
+- ``--start-marker START_MARKER``  
+  Named marker event to use as window start point.
+
+- ``--end END``  
+  End time as percentage or nanoseconds from trace file (e.g., ``75%`` or ``3543724246381057``).
+
+- ``--end-marker END_MARKER``  
+  Named marker event to use as window end point.
+
+- ``--inclusive INCLUSIVE``  
+  ``True``: include events if START or END in window; ``False``: only if BOTH in window (default: ``True``).
+
+**Help:**
+
+- ``-h``, ``--help``  
+  Show help message and exit.
+
+Examples
+++++++++
+
+Convert one database to Perfetto trace:
+
+.. code-block:: bash
+
+   python3 -m rocpd convert -i db1.db --output-format pftrace
+
+Convert two databases to Perfetto trace, set output path and filename, and limit to last 70% of trace:
+
+.. code-block:: bash
+
+   python3 -m rocpd convert -i db1.db db2.db --output-format pftrace -d "./output/" -o "twoFileTraces" --start 30% --end 100%
+
+Convert six databases to CSV and Perfetto trace formats:
+
+.. code-block:: bash
+
+   python3 -m rocpd convert -i db{0..5}.db --output-format csv pftrace -d "~/output_folder/" -o "sixFileTraces"
+
+Convert two databases to CSV, OTF2, and Perfetto trace formats:
+
+.. code-block:: bash
+
+   python3 -m rocpd convert -i db{3,4}.db --output-format csv otf2 pftrace
+

projects/rocprofiler-sdk/source/docs/how-to/using-rocprofiler-sdk-roctx.rst

@@ -0,0 +1,293 @@
+.. meta::
+  :description: Documentation for the usage of rocprofiler-sdk-roctx library
+  :keywords: ROCprofiler-SDK tool, using-rocprofiler-sdk-roctx library, roctx, markers, ranges, rocprofv3, rocprofv3 tool usage, Using rocprofv3, ROCprofiler-SDK command line tool, marker-trace
+
+.. _using-rocprofiler-sdk-roctx:
+
+============
+Using ROCTx
+============
+
+ROCTx is an AMD tools extension library, a cross platform API for annotating code with markers and ranges. The ROCTx API is written in C++.
+In certain situations, such as debugging performance issues in large-scale GPU programs, API-level tracing might be too fine-grained to provide an overview of the program execution.
+In such cases, it is helpful to define specific tasks to be traced. To specify the tasks for tracing, enclose the respective source code with the API calls provided by the ROCTx library.
+This process is also known as instrumentation.
+
+ROCTx annotations
+++++++++++++++++++
+
+ROCTx provides two types of annotations: markers and ranges.
+
+Markers
+========
+
+Markers are used to insert a marker in the code with a message. Creating markers helps you see when a line of code is executed.
+
+Ranges
+=======
+
+Ranges are used to define the scope of code for instrumentation using enclosing API calls.
+A range is a programmer-defined task that has a well-defined start and end code scope.
+You can further refine the scope specified within a range using nested ranges. ``rocprofv3`` also reports the timelines for these nested ranges.
+
+These are the two types of ranges:
+
+- **Push and Pop:** These can be nested to form a stack. The Pop call is automatically associated with a prior Push call on the same thread.
+
+- **Start and End:** These may overlap with other ranges arbitrarily. The Start call returns a handle that must be passed to the End call. These ranges can start and end on different threads.
+
+ROCTx APIs
+===========
+
+Here is the list of useful APIs for code instrumentation:
+
+- ``roctxMark``: Inserts a marker in the code with a message. Creating marks help you see when a line of code is executed.
+- ``roctxRangeStart``: Starts a range. Different threads can start ranges.
+- ``roctxRangePush``: Starts a new nested range.
+- ``roctxRangePop``: Stops the current nested range.
+- ``roctxRangeStop``: Stops the given range.
+- ``roctxProfilerPause``: Requests any currently running profiling tool to stop data collection.
+- ``roctxProfilerResume``: Requests any currently running profiling tool to resume data collection.
+- ``roctxGetThreadId``: Retrieves the ID for the current thread identical to the ID received using ``rocprofiler_get_thread_id(rocprofiler_thread_id_t*)``.
+- ``roctxNameOsThread``: Labels the current CPU OS thread in the profiling tool output with the provided name.
+- ``roctxNameHsaAgent``: Labels the given HSA agent in the profiling tool output with the provided name.
+- ``roctxNameHipDevice``: Labels the HIP device ID in the profiling tool output with the provided name.
+- ``roctxNameHipStream``: Labels the given HIP stream in the profiling tool output with the provided name.
+
+Using ROCTx in the application
++++++++++++++++++++++++++++++++
+
+The following sample code from the MatrixTranspose application shows the usage of ROCTx APIs:
+
+.. code-block:: bash
+
+    #include <rocprofiler-sdk-roctx/roctx.h>
+
+    roctxMark("before hipLaunchKernel");
+    int rangeId = roctxRangeStart("hipLaunchKernel range");
+    roctxRangePush("hipLaunchKernel");
+
+    // Launching kernel from host
+    hipLaunchKernelGGL(matrixTranspose, dim3(WIDTH/THREADS_PER_BLOCK_X, WIDTH/THREADS_PER_BLOCK_Y), dim3(THREADS_PER_BLOCK_X, THREADS_PER_BLOCK_Y), 0,0,gpuTransposeMatrix,gpuMatrix, WIDTH);
+
+    roctxMark("after hipLaunchKernel");
+
+    // Memory transfer from device to host
+    roctxRangePush("hipMemcpy");
+
+    hipMemcpy(TransposeMatrix, gpuTransposeMatrix, NUM * sizeof(float), hipMemcpyDeviceToHost);
+
+    roctxRangePop();  // for "hipMemcpy"
+    roctxRangePop();  // for "hipLaunchKernel"
+    roctxRangeStop(rangeId);
+
+To trace the API calls enclosed within the range, use:
+
+.. code-block:: bash
+
+    rocprofv3 --marker-trace --output-format csv -- <application_path>
+
+Running the preceding command generates a ``marker_api_trace.csv`` file prefixed with the process ID.
+
+.. code-block:: shell
+
+    $ cat 210_marker_api_trace.csv
+
+Here are the contents of ``marker_api_trace.csv`` file:
+
+.. csv-table:: Marker api trace
+   :file: /data/marker_api_trace.csv
+   :widths: 10,10,10,10,10,20,20
+   :header-rows: 1
+
+For the description of the fields in the output file, see :ref:`output-file-fields`.
+
+``roctxProfilerPause`` and ``roctxProfilerResume`` can be used to hide the calls between them. This is useful when you want to hide the calls that are not relevant to your profiling session.
+
+.. code-block:: bash
+
+    #include <rocprofiler-sdk-roctx/roctx.h>
+
+    // Memory transfer from host to device
+    HIP_API_CALL(hipMemcpy(gpuMatrix, Matrix, NUM * sizeof(float), hipMemcpyHostToDevice));
+
+    auto tid = roctx_thread_id_t{};
+    roctxGetThreadId(&tid);
+    roctxProfilerPause(tid);
+    // Memory transfer that should be hidden by profiling tool
+    HIP_API_CALL(
+        hipMemcpy(gpuTransposeMatrix, gpuMatrix, NUM * sizeof(float), hipMemcpyDeviceToDevice));
+    roctxProfilerResume(tid);
+
+    // Launching kernel from host
+    hipLaunchKernelGGL(matrixTranspose,
+                       dim3(WIDTH / THREADS_PER_BLOCK_X, WIDTH / THREADS_PER_BLOCK_Y),
+                       dim3(THREADS_PER_BLOCK_X, THREADS_PER_BLOCK_Y),
+                       0,
+                       0,
+                       gpuTransposeMatrix,
+                       gpuMatrix,
+                       WIDTH);
+
+    // Memory transfer from device to host
+    HIP_API_CALL(
+        hipMemcpy(TransposeMatrix, gpuTransposeMatrix, NUM * sizeof(float), hipMemcpyDeviceToHost));
+
+To trace the preceding code, use:
+
+.. code-block:: shell
+
+    rocprofv3 --marker-trace --hip-trace --output-format csv -- <application_path>
+
+The preceding command generates a ``hip_api_trace.csv`` file prefixed with the process ID. The file contains two ``hipMemcpy`` calls with the in-between ``hipMemcpyDeviceToHost`` call hidden .
+
+.. code-block:: shell
+
+   "Domain","Function","Process_Id","Thread_Id","Correlation_Id","Start_Timestamp","End_Timestamp"
+   "HIP_COMPILER_API","__hipRegisterFatBinary",1643920,1643920,1,320301257609216,320301257636427
+   "HIP_COMPILER_API","__hipRegisterFunction",1643920,1643920,2,320301257650707,320301257678857
+   "HIP_RUNTIME_API","hipGetDevicePropertiesR0600",1643920,1643920,4,320301258114239,320301337764472
+   "HIP_RUNTIME_API","hipMalloc",1643920,1643920,5,320301338073823,320301338247374
+   "HIP_RUNTIME_API","hipMalloc",1643920,1643920,6,320301338248284,320301338399595
+   "HIP_RUNTIME_API","hipMemcpy",1643920,1643920,7,320301338410995,320301631549262
+   "HIP_COMPILER_API","__hipPushCallConfiguration",1643920,1643920,10,320301632131175,320301632134215
+   "HIP_COMPILER_API","__hipPopCallConfiguration",1643920,1643920,11,320301632137745,320301632139735
+   "HIP_RUNTIME_API","hipLaunchKernel",1643920,1643920,12,320301632142615,320301632898289
+   "HIP_RUNTIME_API","hipMemcpy",1643920,1643920,14,320301632901249,320301633934395
+   "HIP_RUNTIME_API","hipFree",1643920,1643920,15,320301643320908,320301643511479
+   "HIP_RUNTIME_API","hipFree",1643920,1643920,16,320301643512629,320301643585639
+
+Resource naming
+++++++++++++++++
+
+``ROCTx`` provides APIs to rename certain resources in the output generated by the profiling tool. You can pass the desired label for a specific resource in the output as an argument to the API. Note that ROCprofiler-SDK doesn't provide any explicit support for how profiling tools handle this request. Support for this capability is tool-specific.
+
+The following table lists the APIs available for labeling the given resources:
+
+.. |br| raw:: html
+
+    <br />
+
+.. list-table:: resource naming
+    :header-rows: 1
+
+    * - Resource
+      - API
+      - Description
+
+    * - OS thread
+      - ``roctxNameOsThread(const char* name)``
+      - Labels the current CPU OS thread with the given name in the output. Note that ROCTx does NOT rename the thread using ``pthread_setname_np``.
+
+    * - HIP runtime
+      - | ``roctxNameHipDevice(const char* name, int device_id)`` |br| |br|
+        | ``roctxNameHipStream(const char* name, const struct ihipStream_t* stream)``
+      - | Labels the given HIP device ID with the given name in the output. |br| |br|
+        | Labels the given HIP stream ID with the given name in the output.
+
+    * - HSA runtime
+      - ``roctxNameHsaAgent(const char* name, const struct hsa_agent_s*)``
+      - Labels the given HSA agent with the given name in the output.
+
+Using ROCTx in the python application
+++++++++++++++++++++++++++++++++++++++
+
+ROCTx APIs can be used in a python application using the ``roctx`` module. The APIs are available as functions in the module. The API names are prefixed with ``roctx`` to avoid name conflicts with other libraries.
+
+The following sample code from the MatrixTranspose application shows the usage of ROCTx APIs in a python application:
+
+.. code-block:: python
+
+    import os
+    import roctx
+    import random
+    from roctx.context_decorators import RoctxRange
+
+    _prefix = os.path.basename(__file__)
+
+    @RoctxRange("matrix_transpose")
+    def matrix_transpose(matrix):
+        nrows = len(matrix)
+        ncols = len(matrix[0]) if nrows > 0 else 0
+        with RoctxRange(f"transpose(nrows={nrows}, ncols={ncols})"):
+            # Transpose the matrix
+            transposed = [[matrix[j][i] for j in range(nrows)] for i in range(ncols)]
+            return transposed
+
+    def generate_matrix(rows, cols):
+        with RoctxRange(f"generate_matrix(rows={rows}, cols={cols})"):
+            return [[random.randint(0, 100) for _ in range(cols)] for _ in range(rows)]
+
+    def run(rows, cols):
+        idx = roctx.rangeStart(f"run(rows={rows}, cols={cols})")
+        matrix = generate_matrix(rows, cols)
+        transposed = matrix_transpose(matrix)
+        roctx.rangeStop(idx)
+        return matrix, transposed
+
+    if __name__ == "__main__":
+        import argparse
+
+        parser = argparse.ArgumentParser()
+        parser.add_argument("-r", "--rows", type=int, default=4, help="Number of rows")
+        parser.add_argument("-c", "--cols", type=int, default=5, help="Number of columns")
+        args = parser.parse_args()
+
+        roctx.mark(f"MatrixTranspose: rows={args.rows}, cols={args.cols}")
+        with RoctxRange("main"):
+            matrix, transposed = run(args.rows, args.cols)
+            print(f"[{_prefix}] Original matrix:")
+            for row in matrix:
+                print(row)
+            print(f"\n[{_prefix}] Transposed matrix:")
+            for row in transposed:
+                print(row)
+
+
+Before using the ``roctx`` module for python application, ensure that the ``roctx`` module is built, installed and available in your python environment.
+
+An example to build and install ``roctx`` module is as follows:    
+
+.. code-block:: shell
+
+   cmake -B build-sdk -DCMAKE_INSTALL_PREFIX=/opt/rocm -DROCPROFILER_PYTHON_VERSIONS="3.10" -DCMAKE_PREFIX_PATH=/opt/rocm
+
+If you are using a different python version, replace ``3.10`` with the appropriate version in the above command.
+Multiple python versions can be specified in the ``ROCPROFILER_PYTHON_VERSIONS`` variable. The roctx module will be built and installed for all the specified python versions.
+
+.. code-block:: shell
+
+    ``cmake -B build-sdk -DCMAKE_INSTALL_PREFIX=/opt/rocm -DROCPROFILER_PYTHON_VERSIONS="3.8;3.9;3.10;3.11;3.12" -DCMAKE_PREFIX_PATH=/opt/rocm``
+
+Based on the python major.minor version and the roctx module install path ("/opt/rocm" in above example), set the ``PYTHONPATH`` environment variable to include the path to the ``roctx`` module.
+    
+.. code-block:: shell
+
+   export PYTHONPATH="<install-path>/lib/pythonX.Y/site-packages:$PYTHONPATH"
+    
+Above example will install the roctx module in ``/opt/rocm/lib/python3.10/site-packages``, set the ``PYTHONPATH`` as follows:
+
+.. code-block:: shell
+
+    export PYTHONPATH=/opt/rocm/lib/python3.10/site-packages:$PYTHONPATH
+
+    
+Once the ``PYTHONPATH`` is set, user should be able to import the `roctx` package:
+
+.. code-block:: shell
+
+   python3 -c "import roctx"
+    
+User can profile the python application which is annotated with ROCTx markers using ``rocprofv3`` as follows:
+    
+.. code-block:: shell
+
+   rocprofv3 --marker-trace --output-format csv -- $(which python) <python_application_path>
+
+The preceding command generates a ``marker_api_trace.csv`` file prefixed with the process ID.
+
+.. csv-table:: Marker api trace for python application
+   :file: /data/python_bindings.csv
+   :widths: 10,10,10,10,10,20,20
+   :header-rows: 1
+

projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3-avail.rst

@@ -0,0 +1,111 @@
+.. meta::
+  :description: Documentation of the usage of rocprofv3-avail
+  :keywords: ROCprofiler-SDK tool usage, rocprofv3-avail usage, rocprofv3 user manual, rocprofv3 usage, rocprofv3 user guide, using rocprofv3, ROCprofiler-SDK tool user guide, ROCprofiler-SDK tool user manual, using ROCprofiler-SDK tool, ROCprofiler-SDK command-line tool, ROCprofiler-SDK CLI, ROCprofiler-SDK command line tool
+
+.. _using-rocprofv3-avail:
+
+======================
+Using rocprofv3-avail
+======================
+
+``rocprofv3-avail`` is a CLI tool that helps you to query the features supported by the hardware and Rocprofiler SDK.
+
+The following sections demonstrate the use of ``rocprofv3-avail`` for querying features using various command-line options.
+
+``rocprofv3-avail`` is installed with ROCm under ``/opt/rocm/bin``. To use the tool from anywhere in the system, export ``PATH`` variable:
+
+.. code-block:: bash
+
+   export PATH=$PATH:/opt/rocm/bin
+
+.. _rocprofv3-avail_cli-options:
+
+Command-line options
+--------------------
+
+The following table lists ``rocprofv3-avail`` command-line options categorized according to their purpose.
+
+.. # COMMENT: The following lines define a line break for use in the table below.
+.. |br| raw:: html
+
+    <br />
+
+.. list-table:: rocprofv3-avail options
+   :header-rows: 1
+
+   * - Purpose
+     - Option
+     - Description
+   
+   * -  avail-aptions commands
+     -  | ``info`` 
+        | ``list`` 
+        | ``pmc-check``  
+     -  | Info options for detailed information of counters, agents, and pc-sampling configurations. 
+        | List options for hardware counters, agents and pc-sampling support.
+        | Checking if a set of counters can be collected together on agent.
+     
+.. code-block:: bash
+
+   rocprofv3-avail list 
+
+The preceding command generates an output listing agents and hardware counters.
+
+.. code-block:: bash
+
+   rocprofv3-avail list --agent
+      
+The preceding command generates an output listing basic info for all agents, if used with ``-d``, only basic info for device ``-d`` is listed.
+Following is the sample output
+
+.. code-block:: bash
+
+   rocprofv3-avail list --pmc
+      
+The preceding command generates an output listing counters for all agents, if used with ``-d``, only counters on the ``-d`` device is listed.
+Output contains following information: logical node id, name and list of PMC counters supported on the agent.
+
+.. code-block:: bash
+
+   rocprofv3-avail list --pc-sampling
+      
+The preceding command generates an output listing agents that supports any kind of PC Sampling. ``-d`` option is not applicable here.
+
+.. code-block:: bash
+
+   rocprofv3-avail info 
+       
+The preceding command generates an output with agent information and listing all counters supported on each agent.
+
+.. code-block:: bash
+
+   rocprofv3-avail info --pmc
+       
+The preceding command generates an output with the pmc info, if used with ``-d`` information of pmc for device ``-d`` is generated.
+Output includes the following information: logical node id, name, counter_name, description of the counter, dimensions, block/expression for every counter.
+
+.. code-block:: bash
+
+   rocprofv3-avail info --pc-sampling 
+       
+The preceding command generates list of supported PC sampling configurations for each agent that supports PC sampling. ``-d`` option is not applicable here.
+Output has following information: logical node id, method supported, unit, minimum sampling interval, maximum sampling interval
+flags. 
+
+.. code-block:: bash
+
+   rocprofv3-avail pmc-check  [pmc [pmc...]] 
+       
+The preceding command checks if the pmc can be collected together
+
+.. code-block:: bash
+
+   rocprofv3-avail pmc-check -d 0 <pmc1> <pmc2> <pmc3>:device=1
+
+The preceding command checks if the pmc1 and pmc2 can be collected together on agent 0 and pmc3 on agent 1
+  
+.. note::
+
+  All commands writes to the standard output.
+
+       

projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3-with-mpi.rst

@@ -0,0 +1,170 @@
+.. meta::
+  :description: Documentation of the MPI usage for rocprofv3
+  :keywords: ROCprofiler-SDK tool, mpirun, rocprofv3, rocprofv3 tool usage, mpich, ROCprofiler-SDK command line tool, ROCprofiler-SDK CLI
+
+
+.. _using-rocprofv3-with-mpi:
+
+Using rocprofv3 with MPI
++++++++++++++++++++++++++++++
+
+Message Passing Interface (MPI) is a standardized and portable message-passing system designed to function on a wide variety of parallel computing architectures. MPI is widely used for developing parallel applications and is considered the de facto standard for communication in high-performance computing (HPC) environments.
+MPI applications are parallel programs that run across multiple processes, which can be distributed over one or more nodes.
+
+For MPI applications or other job launchers such as `SLURM <https://slurm.schedmd.com/documentation.html>`_, place ``rocprofv3`` inside the job launcher. The following example demonstrates how to use ``rocprofv3`` with MPI:
+
+.. code-block:: bash
+
+    mpirun -n 4 rocprofv3 --hip-trace --output-format csv -- <application_path>
+
+The preceding command runs the application with ``rocprofv3`` and generates the trace file for each rank. The trace files are prefixed with the process ID.
+
+.. code-block:: bash
+
+    2293213_agent_info.csv
+    2293213_hip_api_trace.csv
+    2293214_agent_info.csv
+    2293214_hip_api_trace.csv
+    2293212_agent_info.csv
+    2293212_hip_api_trace.csv
+    2293215_agent_info.csv
+    2293215_hip_api_trace.csv
+
+Since the data collection is performed in-process, it's ideal to collect data from within the processes launched by MPI. When ``rocprofv3`` is run outside of ``mpirun``, the tool library is loaded into the `mpirun` executable..
+Collecting data outside of ``mpirun`` works but fetches agent info for the ``mpirun`` process too. For example:
+
+.. code-block:: bash
+
+    rocprofv3 --hip-trace -d %h.%p.%env{OMPI_COMM_WORLD_RANK}% --output-format csv -- mpirun -n 2  <application_path>
+
+In the preceding example, an extra agent info file is generated for the ``mpirun`` process. The trace files are prefixed with the hostname, process ID, and the MPI rank.
+
+.. code-block:: bash
+
+    ubuntu-latest.3000020.1/3000020_agent_info.csv
+    ubuntu-latest.3000020.0/3000019_agent_info.csv
+    ubuntu-latest.3000020.1/3000020_hip_api_trace.csv
+    ubuntu-latest.3000020.0/3000019_hip_api_trace.csv
+
+ROCTx annotations
+===================
+
+For an MPI application, you can use ROCTx annotations to mark the start and end of the MPI code region. The following example demonstrates how to use ROCTx annotations with MPI:
+
+.. code-block:: cpp
+
+    #include <roctx.h>
+    #include <mpi.h>
+    ...
+
+    void run(int rank, int tid, int dev_id, int argc, char** argv)
+    {
+        auto roctx_run_id = roctxRangeStart("run");
+
+        const auto mark = [rank, tid, dev_id](std::string_view suffix) {
+            auto _ss = std::stringstream{};
+            _ss << "run/rank-" << rank << "/thread-" << tid << "/device-" << dev_id << "/" << suffix;
+            roctxMark(_ss.str().c_str());
+        };
+
+        mark("begin");
+
+        constexpr unsigned int M = 4960 * 2;
+        constexpr unsigned int N = 4960 * 2;
+
+        unsigned long long nitr = 0;
+        unsigned long long nsync = 0;
+
+        if(argc > 2) nitr = atoll(argv[2]);
+        if(argc > 3) nsync = atoll(argv[3]);
+
+        hipStream_t stream = {};
+
+        printf("[transpose] Rank %i, thread %i assigned to device %i\n", rank, tid, dev_id);
+        HIP_API_CALL(hipSetDevice(dev_id));
+        HIP_API_CALL(hipStreamCreate(&stream));
+
+        auto_lock_t _lk{print_lock};
+        std::cout << "[transpose][" << rank << "][" << tid << "] M: " << M << " N: " << N << std::endl;
+        _lk.unlock();
+
+        std::default_random_engine         _engine{std::random_device{}() * (rank + 1) * (tid + 1)};
+        std::uniform_int_distribution<int> _dist{0, 1000};
+
+        ...
+
+        auto t1 = std::chrono::high_resolution_clock::now();
+        for(size_t i = 0; i < nitr; ++i)
+        {
+            roctxRangePush("run/iteration");
+            transpose<<<grid, block, 0, stream>>>(in, out, M, N);
+            check_hip_error();
+            if(i % nsync == (nsync - 1))
+            {
+                roctxRangePush("run/iteration/sync");
+                HIP_API_CALL(hipStreamSynchronize(stream));
+                roctxRangePop();
+            }
+            roctxRangePop();
+        }
+        auto t2 = std::chrono::high_resolution_clock::now();
+        HIP_API_CALL(hipStreamSynchronize(stream));
+        HIP_API_CALL(hipMemcpyAsync(out_matrix, out, size, hipMemcpyDeviceToHost, stream));
+        double time = std::chrono::duration_cast<std::chrono::duration<double>>(t2 - t1).count();
+        float  GB   = (float) size * nitr * 2 / (1 << 30);
+
+        print_lock.lock();
+        std::cout << "[transpose][" << rank << "][" << tid << "] Runtime of transpose is " << time
+                  << " sec\n";
+        std::cout << "[transpose][" << rank << "][" << tid
+                  << "] The average performance of transpose is " << GB / time << " GBytes/sec"
+                  << std::endl;
+        print_lock.unlock();
+
+        ...
+
+        mark("end");
+
+        roctxRangeStop(roctx_run_id);
+    }
+
+This preceding sample generates output similar to the following:
+
+.. code-block:: shell
+
+    "MARKER_CORE_API","run/rank-0/thread-0/device-0/begin",2936128,2936128,5,432927100747635,432927100747635
+    "MARKER_CORE_API","run/rank-0/thread-1/device-1/begin",2936128,2936397,7,432927100811475,432927100811475
+    "MARKER_CORE_API","run/iteration",2936128,2936397,22,432928615598809,432928648197081
+    "MARKER_CORE_API","run/iteration",2936128,2936397,61,432928648229081,432928648234041
+    "MARKER_CORE_API","run/iteration",2936128,2936397,67,432928648234701,432928648239621
+    "MARKER_CORE_API","run/iteration",2936128,2936397,73,432928648239971,432928648244141
+    "MARKER_CORE_API","run/iteration/sync",2936128,2936397,84,432928648249791,432928664871094
+    ...
+
+    "MARKER_CORE_API","run/iteration",2936128,2936128,6313,432929397644269,432929397648369
+    "MARKER_CORE_API","run/iteration/sync",2936128,2936128,6324,432929397653119,432929401455250
+    "MARKER_CORE_API","run/iteration",2936128,2936128,6319,432929397648779,432929401455640
+    "MARKER_CORE_API","run/rank-0/thread-1/device-1/end",2936128,2936397,6339,432929527301990,432929527301990
+    "MARKER_CORE_API","run",2936128,2936397,6,432927100787035,432929527313480
+    "MARKER_CORE_API","run/rank-0/thread-0/device-0/end",2936128,2936128,6342,432929612438185,432929612438185
+    "MARKER_CORE_API","run",2936128,2936128,4,432927100729745,432929612448285
+
+Output format features
+=======================
+
+To collect the profiles of the individual MPI processes, use ``rocprofv3`` with output directory option to send output to unique files.
+
+.. code-block:: bash
+
+    mpirun -n 2 rocprofv3 --hip-trace -d %h.%p.%env{OMPI_COMM_WORLD_RANK}% --output-format csv --  <application_path>
+
+To see the placeholders supported by the output directory option, see :ref:`output directory placeholders <output_field_format>`.
+
+Assuming the hostname as `ubuntu-latest`, the process IDs as 3000020 and 3000019, the generated output file names are:
+
+.. code-block:: bash
+
+    ubuntu-latest.3000020.1/ubuntu-latest/3000020_agent_info.csv
+    ubuntu-latest.3000019.0/ubuntu-latest/3000019_agent_info.csv
+    ubuntu-latest.3000020.1/ubuntu-latest/3000020_hip_api_trace.csv
+    ubuntu-latest.3000019.0/ubuntu-latest/3000019_hip_api_trace.csv

projects/rocprofiler-sdk/source/docs/how-to/using-rocprofv3-with-openmp.rst

@@ -0,0 +1,90 @@
+.. meta::
+  :description: Documentation for using rocprofv3 with OpenMP applications
+  :keywords: ROCprofiler-SDK tool, OpenMP, rocprofv3, rocprofv3 tool usage, ROCprofiler-SDK command line tool, ROCprofiler-SDK CLI
+
+
+.. _using-rocprofv3-with-openmp:
+
+Using rocprofv3 with OpenMP
++++++++++++++++++++++++++++++
+
+`rocprofv3` does not provide native support for profiling CPU-side OpenMP code. However, when OpenMP is used to offload computations to AMD GPUs (for example, via OpenMP target offload), `rocprofv3` can capture and profile GPU activities initiated by these offloaded regions. Note that profiling of CPU-side OpenMP parallel regions is not supported.
+
+Example: Vector Addition Using OpenMP Offload on AMD GPUs
+---------------------------------------------------------
+
+The following example demonstrates how to perform vector addition using OpenMP target offload, enabling execution of the workload on AMD GPUs.
+
+**Key Steps:**
+
+- Initialize input arrays on the host.
+- Offload the vector addition computation to the GPU using OpenMP directives.
+- Retrieve and verify the results on the host.
+
+.. code-block:: c
+
+    #include <stdio.h>
+    #include <omp.h>
+
+    #define N 1024
+
+    int main() {
+        float a[N], b[N], c[N];
+
+        // Initialize input arrays
+        for (int i = 0; i < N; ++i) {
+            a[i] = i * 1.0f;
+            b[i] = (N - i) * 1.0f;
+        }
+
+        // Offload vector addition to GPU
+        #pragma omp target teams distribute parallel for map(to: a[0:N], b[0:N]) map(from: c[0:N])
+        for (int i = 0; i < N; ++i) {
+            c[i] = a[i] + b[i];
+        }
+
+        // Verify results
+        int errors = 0;
+        for (int i = 0; i < N; ++i) {
+            if (c[i] != N * 1.0f) {
+                errors++;
+            }
+        }
+
+        if (errors == 0) {
+            printf("Vector addition successful!\\n");
+        } else {
+            printf("Vector addition failed with %d errors.\\n", errors);
+        }
+
+        return 0;
+    }
+
+
+Building the OpenMP Offload Application
+---------------------------------------
+
+To compile the application for AMD GPU offload, use the following command:
+
+.. code-block:: bash
+
+    amdclang++ -fopenmp -fopenmp-targets=amdgcn-amd-amdhsa -L/opt/rocm/lib --offload-arch=gfx9xx -o vector_add <application>
+
+Profiling the Application with rocprofv3
+----------------------------------------
+
+To profile the GPU activity during execution, run the application with `rocprofv3`:
+
+.. code-block:: bash
+
+    rocprofv3 -s --output-format csv -- ./vector_add
+
+Upon execution, `rocprofv3` will generate several CSV trace files, such as:
+
+- `<pid>_kernel_trace.csv`
+- `<pid>_hsa_api_trace.csv`
+- `<pid>_memory_copy_trace.csv`
+- `<pid>_memory_allocation_trace.csv`
+- `<pid>_scratch_memory_trace.csv`
+
+These files contain detailed profiling information about GPU kernel execution, HSA API calls, memory operations, and more, enabling comprehensive analysis of the offloaded workload.

projects/rocprofiler-sdk/source/docs/how-to/using-thread-trace.rst

@@ -0,0 +1,234 @@
+.. meta::
+  :description: Documentation of the usage of thread trace with rocprofv3 command-line tool
+  :keywords: rocprofv3, rocprofv3 tool usage, Using rocprofv3, ROCprofiler-SDK command line tool, Thread Trace, SQTT, ATT, ROCprof Trace Decoder, ROCprof Compute Viewer
+
+.. _using-thread-trace:
+
+============================
+Using thread trace
+============================
+
+Thread trace is a shader execution tracing technique capable of profiling wavefronts at the instruction timing level.
+This is a low-level tracing and profiling feature that targets a single or a few kernel executions.
+
+Thread trace features include:
+
+* Near cycle-accurate instruction tracing
+* Exact thread or wave execution path
+* Wave scheduling and stall timing analysis
+* Instruction and source level hotspots
+* Extremely fast and granular counter collection (AMD Instinct)
+
+Supported devices:
+
+* AMD Instinct: MI200 and MI300 series
+* AMD Radeon: gfx10, gfx11 and gfx12
+
+Thread trace profiling is performed in the following steps:
+
+1. Tracing (data collection) - Uses ROCprofiler-SDK thread trace service API
+2. Decoding (analysis) - Uses ROCprof Trace Decoder API
+3. Visualization - Requires ROCprof Compute Viewer
+
+Tracing and decoding is handled by ``rocprofv3`` while visualization is handled by the ROCprof Compute Viewer.
+
+Prerequisites
+=========
+
+- aqlprofile:
+
+  * ROCm 7.x build, or
+
+  * Early release can be `built from source <https://github.com/rocm/aqlprofile>`_
+
+  * Otherwise, ``rocprofv3`` throws error "INVALID_SHADER_DATA" or "Agent not supported".
+
+- Installation of ROCprof Trace Decoder component:
+
+  * For binary files, see `ROCprof trace decoder release page <https://github.com/ROCm/rocprof-trace-decoder/releases>`_.
+
+  * Default install location is ``/opt/rocm/lib``
+   
+  * For custom location, use:
+
+      * Parameter ``--att-library-path``, or
+
+      * Environment variable ``ROCPROF_ATT_LIBRARY_PATH``
+   
+
+.. _thread-trace-parameters:
+
+rocprofv3 parameters for thread tracing
+============================
+
+To collect thread trace with default parameters, use:
+
+.. code-block:: bash
+
+  rocprofv3 --att -d <output_dir> -- <application_path>
+
+The following table lists the parameters relevant to thread tracing:
+
++--------------------------+---------+---------+-----------+--------------------------------------------------------------+
+| Parameter                | Type    | Range   | Typical   | Description                                                  |
++==========================+=========+=========+===========+==============================================================+
+| att-target-cu            | Integer | 0 - 15  | 1         | Defines the CU used to gather detail tokens (WGP on Navi)    |
++--------------------------+---------+---------+-----------+--------------------------------------------------------------+
+| att-shader-engine-mask   | Bitmask | 1 - ~0u | 0x1       | Defines the Shader Engines (SE) to be traced. Max 2^32 - 1   |
++--------------------------+---------+---------+-----------+--------------------------------------------------------------+
+| att-simd-select          | Integer | 0 - 0xF | gfx9: 0xF | Defines one or more SIMDs to be traced, out of four.         |
+|                          |         |         | Navi: 0x0 | Bitmask on GFX9 and SIMD_ID[0,3] on Navi.                    |
++--------------------------+---------+---------+-----------+--------------------------------------------------------------+
+| kernel-iteration-range   | List    |         |           | Defines dispatch iteration of the kernel to be profiled      |
++--------------------------+---------+---------+-----------+--------------------------------------------------------------+
+| kernel-include-regex     | String  | Any     |           | Profiles kernel names matching the regex                     |
++--------------------------+---------+---------+-----------+--------------------------------------------------------------+
+| kernel-exclude-regex     | String  | Any     |           | Doesn't profile kernel names matching the regex              |
++--------------------------+---------+---------+-----------+--------------------------------------------------------------+
+| att-buffer-size          | Bytes   | 1MB-2GB | 96MB      | Specifies the trace buffer size. This is shared for all SEs. |
+|                          |         |         |           | Increase this value if the buffer tends to get full.         |
++--------------------------+---------+---------+-----------+--------------------------------------------------------------+
+| att-serialize-all        | Bool    |         | False     | If set to "True", turns on serialization for untraced kernels|
++--------------------------+---------+---------+-----------+--------------------------------------------------------------+
+| att-perfcounter-ctrl     | Integer | 1 - 32  | 2~8       | Available only in gfx9. Streams SQ performance counters to   |
+|                          |         |         |           | the thread trace buffer in the given relative period. As     |
+|                          |         |         |           | this uses high bandwidth, a value too low can cause or worsen|
+|                          |         |         |           | "Data Lost" events and warnings.                             |
++--------------------------+---------+---------+-----------+--------------------------------------------------------------+
+| att-perfcounters         | String  | SQ-only |           | Available only in gfx9. Specifies the list of SQ counters.   |
+|                          |         |         |           | To list all counters, use "rocprofv3 --list-avail``.         |
++--------------------------+---------+---------+-----------+--------------------------------------------------------------+
+| att-activity             | Integer | 1 - 16  | 5~10      | Available only in gfx9.                                      |
+|                          |         |         |           | Shorthand for att-perfcounter-ctrl and the att-perfcounters  |
+|                          |         |         |           | related to compute unit activity such as VALU, SALU, etc.    |
++--------------------------+---------+---------+-----------+--------------------------------------------------------------+
+
+For AMD Instinct accelerators, enable perfmon streaming using:
+
+.. code-block:: bash
+
+  rocprofv3 --att --att-activity 8 -- <application_path>
+
+For AMD Radeon, the ``simd-select`` parameter is a SIMD ID defaulting to 3. For some applications it's best to use:
+
+.. code-block:: bash
+
+  rocprofv3 --att --att-simd-select 0x0 -- <application_path>
+
+
+Using input file
+===========
+
+As explained in the preceding section, you can specify parameters on the command line or use a JSON input file:
+
+.. code-block:: text
+
+  {
+      "jobs": [
+          {
+              "advanced_thread_trace": true,
+              "att_target_cu": 1,
+              "att_shader_engine_mask": "0x1",
+              "att_simd_select": "0xF",
+              "att_buffer_size": "0x6000000"
+          }
+      ]
+  }
+
+Thread tracing for multiple kernel instances
+=============================
+
+By default, ``rocprofv3`` enables thread trace only once per kernel instance. This implies that if an application launches the same kernel multiple times, only the first instance will be traced.
+To enable thread trace for multiple kernel instances, use the ``kernel-iteration-range`` parameter.
+It's recommended to use ``kernel-include-regex`` parameter to filter the desired kernel names instead of tracing everything.
+
+.. _output-files:
+
+rocprofv3 output files
+===============
+
+After the application finishes executing, ROCprof Trace Decoder runs automatically and the following output files are generated:
+
+- stats_*.csv files:
+
+  * Contains a summary of instruction latency per kernel.
+  
+- ui_output_agent_{agent_id}_dispatch_{dispatch_id} directory:
+  
+  * Contains detailed tracing information in the form of .json files.
+    
+  * This directory can be opened using the `ROCprof Compute Viewer <https://rocm.docs.amd.com/projects/rocprof-compute-viewer/en/amd-mainline/>`_.
+
+- Raw files:
+
+  * .att - Raw SQTT data. Can be used with the ROCprof Trace Decoder for further analysis.
+  
+  * .out - Code object binaries (executable). Can be used with ISA analysis tools.
+
+.. _csv-content:
+
+Stats CSV
+------------
+
+Here is a sample stats_*.csv file that is generated by the rocprofv3 tool.
+
++---------+-------+---------------------------------------------+----------+---------+-------+------+-------------------+
+| Codeobj | Vaddr | Instruction                                 | Hitcount | Latency | Stall | Idle | Source            |
++=========+=======+=============================================+==========+=========+=======+======+===================+
+| 11      | 5888  | s_load_dwordx4 s[40:43], s[0:1], 0x18       | 48       | 276     | 96    | 48   | kernel.py:391     |
++---------+-------+---------------------------------------------+----------+---------+-------+------+-------------------+
+| 11      | 5896  | s_load_dwordx2 s[38:39], s[0:1], 0x28       | 48       | 192     | 0     | 0    | kernel.py:391     |
++---------+-------+---------------------------------------------+----------+---------+-------+------+-------------------+
+| 11      | 5904  | s_ashr_i32 s3, s2, 31                       | 48       | 260     | 0     | 0    | kernel.py:395     |
++---------+-------+---------------------------------------------+----------+---------+-------+------+-------------------+
+| 11      | 5908  | s_add_i32 s7, s2, s3                        | 48       | 196     | 0     | 0    | kernel.py:395     |
++---------+-------+---------------------------------------------+----------+---------+-------+------+-------------------+
+
+The columns of the stats_*.csv file are described here:
+
+* **Codeobj:** The code object load ID assigned by ROCprofiler-SDK.
+
+* **Vaddr:** ELF vaddr.
+
+* **Hitcount:** The number of times a particular instruction is executed while adding all the traced waves.
+
+* **Latency:** Total latency in cycles, defined as "Stall time + Issue time" for gfx9 or "Stall time + Execute time" for gfx10+.
+
+* **Stall:** The total number of cycles the hardware pipe couldn't issue an instruction. 
+
+  * Usually caused when the hardware unit is busy, such as TCP or LDS backpressure.
+    
+* **Idle:** The total time gap between the completion of previous instruction and the beginning of the current instruction. The idle time can be caused by:
+
+  * Arbiter loss
+    
+  * Source or destination register dependency
+    
+  * Instruction cache miss
+    
+* **Source:** The original source line of code assigned by the compiler.
+
+  * Requires compiling with debug symbols.
+    
+
+Troubleshooting
+===============
+
+For some applications, stats_*.csv file could be empty even for a valid kernel dispatch.
+Thread trace is limited to a single CU per SE (``att-target-cu``). If a kernel dispatch doesn't launch enough waves to populate the whole GPU, there's a possibility of no wave getting assigned to the ``target_cu``. In such cases, there's nothing to be traced. 
+Here are some options to handle this:
+
+* Launch more waves.
+
+* Swap the ``target_cu``.
+
+* Set the ``--att-shader-engine-mask`` to 0x11111111, or possibly to 0xFFFFFFFF
+
+  * A number too high can cause packet losses and/or lead to a full buffer.
+    
+* Set the ``HSA_CU_MASK`` to mask out all CUs but the target. For more details, see `setting CUs <https://rocm.docs.amd.com/en/latest/how-to/setting-cus.html>`_.
+
+  * If only the ``target_cu`` (or a few CUs) are not masked out, then all or most waves will be assigned to the ``target_cu``.
+    
+  * This can potentially cause low performance in high-demanding kernels.
+    

projects/rocprofiler-sdk/source/docs/index.rst

@@ -0,0 +1,62 @@
+.. meta::
+  :description: ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software
+  :keywords: ROCprofiler-SDK tool, ROCprofiler-SDK library, rocprofv3, ROCprofiler-SDK API, ROCprofiler-SDK documentation
+
+.. _index:
+
+********************************
+ROCprofiler-SDK documentation
+********************************
+
+ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software.
+It supports application tracing to provide a big picture of the GPU application execution and kernel counter collection to provide low-level hardware details from the performance counters.
+The ROCprofiler-SDK library provides runtime-independent APIs for tracing runtime calls and asynchronous activities such as GPU kernel dispatches and memory moves. The tracing includes callback APIs for runtime API tracing and activity APIs for asynchronous activity records logging.
+
+In summary, ROCprofiler-SDK combines `ROCProfiler <https://rocm.docs.amd.com/projects/rocprofiler/en/latest/index.html>`_ and `ROCTracer <https://rocm.docs.amd.com/projects/roctracer/en/latest/index.html>`_.
+You can utilize the ROCprofiler-SDK to develop a tool for profiling and tracing HIP applications on ROCm software.
+
+The code is open and hosted at `<https://github.com/ROCm/rocprofiler-sdk>`_.
+
+
+The documentation is structured as follows:
+
+.. grid:: 2
+  :gutter: 3
+
+  .. grid-item-card:: Install
+
+    * :ref:`installing-rocprofiler-sdk`
+
+  .. grid-item-card:: How to
+
+    * :doc:`Samples <how-to/samples>`
+    * :ref:`using-rocprofv3`
+    * :ref:`using-rocprofv3-avail`
+    * :ref:`using-rocpd-output-format`
+    * :ref:`using-rocprofiler-sdk-roctx`
+    * :ref:`using-rocprofv3-with-mpi`
+    * :ref:`using-rocprofv3-with-openmp`
+    * :ref:`using-pc-sampling`
+    * :ref:`using-thread-trace`
+
+  .. grid-item-card:: API reference
+
+    * :doc:`Tool library <api-reference/tool_library>`
+    * :ref:`runtime-intercept-tables`
+    * :doc:`Buffered services <api-reference/buffered_services>`
+    * :doc:`Callback services <api-reference/callback_services>`
+    * :doc:`Counter collection services <api-reference/counter_collection_services>`
+    * :doc:`PC sampling <api-reference/pc_sampling>`
+    * :doc:`ROCprof Trace Decoder <api-reference/thread_trace>`
+    * :doc:`ROCprofiler-SDK API <api-reference/rocprofiler-sdk_api_reference>`
+    * :doc:`ROCTx API <api-reference/rocprofiler-sdk-roctx_api_reference>`
+
+  .. grid-item-card:: Conceptual
+
+    * :ref:`comparing-with-legacy-tools`
+
+To contribute to the documentation, refer to
+`Contributing to ROCm <https://rocm.docs.amd.com/en/latest/contribute/contributing.html>`_.
+
+You can find licensing information on the
+`Licensing <https://rocm.docs.amd.com/en/latest/about/license.html>`_ page.

projects/rocprofiler-sdk/source/docs/install/installation.rst

@@ -0,0 +1,131 @@
+.. meta::
+   :description: "ROCprofiler-SDK is a tooling infrastructure for profiling general-purpose GPU compute applications running on the ROCm software."
+   :keywords: "Installing ROCprofiler-SDK, Install ROCprofiler-SDK, Build ROCprofiler-SDK"
+
+.. _installing-rocprofiler-sdk:
+
+Installing ROCprofiler-SDK
+=============================
+
+This document provides information required to install ROCprofiler-SDK from source.
+
+Supported systems
+-----------------
+
+ROCprofiler-SDK is supported only on Linux. The following distributions are tested:
+
+- Ubuntu 20.04
+- Ubuntu 22.04
+- Ubuntu 24.04
+- OpenSUSE 15.5
+- OpenSUSE 15.6
+- Red Hat 8.8
+- Red Hat 8.9
+- Red Hat 8.10
+- Red Hat 9.2
+- Red Hat 9.3
+- Red Hat 9.4
+
+ROCprofiler-SDK might operate as expected on other `Linux distributions <https://rocm.docs.amd.com/projects/install-on-linux/en/latest/reference/system-requirements.html#supported-operating-systems>`_, but has not been tested.
+
+Identifying the operating system
+--------------------------------
+
+To identify the Linux distribution and version, see the ``/etc/os-release`` and ``/usr/lib/os-release`` files:
+
+.. code-block:: bash
+
+    $ cat /etc/os-release
+    NAME="Ubuntu"
+    VERSION="20.04.4 LTS (Focal Fossa)"
+    ID=ubuntu
+    ...
+    VERSION_ID="20.04"
+    ...
+
+The relevant fields are ``ID`` and the ``VERSION_ID``.
+
+Build requirements
+------------------
+
+To build ROCprofiler-SDK, install ``CMake`` as explained in the following section.
+
+Install CMake
+++++++++++++++
+
+Install `CMake <https://cmake.org/>`_ version 3.21 (or later).
+
+.. note::
+    If the ``CMake`` installed on the system is too old, you can install a new version using various methods. One of the easiest options is to use PyPi (Python's pip).
+
+.. code-block:: bash
+
+    /usr/local/bin/python -m pip install --user 'cmake==3.22.0'
+    export PATH=${HOME}/.local/bin:${PATH}
+
+Building ROCprofiler-SDK from source
+-------------------------------------
+
+.. code-block:: bash
+
+    git clone https://github.com/ROCm/rocprofiler-sdk.git rocprofiler-sdk-source
+    cmake                                         \
+        -B rocprofiler-sdk-build                \
+        -D ROCPROFILER_BUILD_TESTS=ON           \
+        -D ROCPROFILER_BUILD_SAMPLES=ON         \
+        -D CMAKE_INSTALL_PREFIX=/opt/rocm       \
+        rocprofiler-sdk-source
+
+    cmake --build rocprofiler-sdk-build --target all --parallel 8
+
+Installing ROCprofiler-SDK
+---------------------------
+
+To install ROCprofiler-SDK from the ``rocprofiler-sdk-build`` directory, run:
+
+.. code-block:: bash
+
+    cmake --build rocprofiler-sdk-build --target install
+
+Testing ROCprofiler-SDK
+------------------------
+
+To run the built tests, ``cd`` into the ``rocprofiler-sdk-build`` directory and run:
+
+.. code-block:: bash
+
+    ctest --output-on-failure -O ctest.all.log
+
+
+.. note::
+    Running a few of these tests require you to install `pandas <https://pandas.pydata.org/>`_ and `pytest <https://docs.pytest.org/en/stable/>`_ first.
+
+.. code-block:: bash
+
+    /usr/local/bin/python -m pip install -r requirements.txt
+
+Install using package manager
+------------------------------
+
+If you have ROCm version 6.2 or later installed, you can use the package manager to install a prebuilt copy of ROCprofiler-SDK.
+
+.. tab-set::
+
+   .. tab-item:: Ubuntu
+
+      .. code-block:: shell
+
+         $ sudo apt install rocprofiler-sdk
+
+   .. tab-item:: Red Hat Enterprise Linux
+
+      .. code-block:: shell
+
+         $ sudo dnf install rocprofiler-sdk
+
+   .. tab-item:: SUSE Linux Enterprise Server
+
+      .. code-block:: shell
+
+         $ sudo zypper install rocprofiler-sdk
+

projects/rocprofiler-sdk/source/docs/license.rst

@@ -0,0 +1,5 @@
+=======
+License
+=======
+
+.. include:: ../../LICENSE

projects/rocprofiler-sdk/source/docs/rocprofiler-sdk-roctx.dox.in

@@ -0,0 +1,411 @@
+# Doxyfile 1.9.8
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = ROCTx developer API
+PROJECT_NUMBER         = @ROCPROFILER_VERSION@
+PROJECT_BRIEF          = "ROCm Profiling API and tools"
+PROJECT_LOGO           =
+OUTPUT_DIRECTORY       = _doxygen/roctx
+CREATE_SUBDIRS         = NO
+CREATE_SUBDIRS_LEVEL   = 8
+ALLOW_UNICODE_NAMES    = YES
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       =
+ALWAYS_DETAILED_SEC    = YES
+INLINE_INHERITED_MEMB  = YES
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        = @SOURCE_DIR@/source/include \
+                         @SOURCE_DIR@/build-docs/source/include
+STRIP_FROM_INC_PATH    = @SOURCE_DIR@/source/include \
+                         @SOURCE_DIR@/build-docs/source/include
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = NO
+JAVADOC_BANNER         = NO
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = YES
+PYTHON_DOCSTRING       = YES
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 4
+ALIASES                =
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+OPTIMIZE_OUTPUT_SLICE  = NO
+EXTENSION_MAPPING      = hpp=C++ \
+                         cpp=C++ \
+                         hh=C++ \
+                         cc=C++ \
+                         h=C \
+                         c=C \
+                         py=Python
+MARKDOWN_SUPPORT       = YES
+TOC_INCLUDE_HEADINGS   = 2
+MARKDOWN_ID_STYLE      = DOXYGEN
+AUTOLINK_SUPPORT       = YES
+BUILTIN_STL_SUPPORT    = YES
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+IDL_PROPERTY_SUPPORT   = YES
+DISTRIBUTE_GROUP_DOC   = NO
+GROUP_NESTED_COMPOUNDS = YES
+SUBGROUPING            = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS  = YES
+TYPEDEF_HIDES_STRUCT   = YES
+LOOKUP_CACHE_SIZE      = 5
+NUM_PROC_THREADS       = 0
+TIMESTAMP              = NO
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = NO
+EXTRACT_PRIVATE        = NO
+EXTRACT_PRIV_VIRTUAL   = NO
+EXTRACT_PACKAGE        = NO
+EXTRACT_STATIC         = NO
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+RESOLVE_UNNAMED_PARAMS = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = NO
+HIDE_SCOPE_NAMES       = NO
+HIDE_COMPOUND_REFERENCE= NO
+SHOW_HEADERFILE        = YES
+SHOW_INCLUDE_FILES     = YES
+SHOW_GROUPED_MEMB_INC  = YES
+FORCE_LOCAL_INCLUDES   = NO
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_MEMBERS_CTORS_1ST = YES
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+STRICT_PROTO_MATCHING  = NO
+GENERATE_TODOLIST      = NO
+GENERATE_TESTLIST      = NO
+GENERATE_BUGLIST       = NO
+GENERATE_DEPRECATEDLIST= NO
+ENABLED_SECTIONS       =
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_FILES             = YES
+SHOW_NAMESPACES        = YES
+FILE_VERSION_FILTER    =
+LAYOUT_FILE            =
+CITE_BIB_FILES         =
+#---------------------------------------------------------------------------
+# Configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = NO
+WARN_IF_DOC_ERROR      = YES
+WARN_IF_INCOMPLETE_DOC = YES
+WARN_NO_PARAMDOC       = YES
+WARN_IF_UNDOC_ENUM_VAL = NO
+WARN_AS_ERROR          = YES
+WARN_FORMAT            = "---> WARNING! $file:$line: $text"
+WARN_LINE_FORMAT       = "at line $line of file $file"
+WARN_LOGFILE           =
+#---------------------------------------------------------------------------
+# Configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT                  = @SOURCE_DIR@/README.md \
+                         @SOURCE_DIR@/source/include/rocprofiler-sdk-roctx \
+                         @SOURCE_DIR@/build-docs/source/include/rocprofiler-sdk-roctx/version.h
+INPUT_ENCODING         = UTF-8
+INPUT_FILE_ENCODING    =
+FILE_PATTERNS          = *.h \
+                         *.hh \
+                         *.hpp \
+                         *.c \
+                         *.cc \
+                         *.cxx \
+                         *.cpp \
+                         *.c++ \
+                         *.icc \
+                         *.tcc \
+                         conf.py
+RECURSIVE              = YES
+EXCLUDE                = @SOURCE_DIR@/README.md
+EXCLUDE_SYMLINKS       = YES
+EXCLUDE_PATTERNS       = */.git/* \
+                         @SOURCE_DIR@/**/tests/* \
+                         @SOURCE_DIR@/**/scripts/* \
+                         @SOURCE_DIR@/**/docs/* \
+                         @SOURCE_DIR@/**/cmake/* \
+                         @SOURCE_DIR@/**/external/* \
+                         @SOURCE_DIR@/**/RPM/* \
+                         @SOURCE_DIR@/**/ISSUE_TEMPLATE/* \
+                         @SOURCE_DIR@/**/rocprofiler-sdk/**/* \
+                         @SOURCE_DIR@/**/rocprofiler-sdk-roctx/api_trace.h
+EXCLUDE_SYMBOLS        = "std::*" \
+                         "ROCPROFILER_ATTRIBUTE" \
+                         "ROCPROFILER_API" \
+                         "ROCPROFILER_NONNULL" \
+                         "ROCPROFILER_PUBLIC_API" \
+                         "ROCPROFILER_HIDDEN_API" \
+                         "ROCPROFILER_EXPORT_DECORATOR" \
+                         "ROCPROFILER_IMPORT_DECORATOR" \
+                         "ROCPROFILER_EXPORT" \
+                         "ROCPROFILER_IMPORT" \
+                         "ROCPROFILER_HANDLE_LITERAL" \
+                         "ROCPROFILER_EXTERN_C_INIT" \
+                         "ROCPROFILER_EXTERN_C_FINI" \
+                         "ROCTX_API" \
+                         "ROCTX_NONNULL"
+EXAMPLE_PATH           = @SOURCE_DIR@/samples
+EXAMPLE_PATTERNS       = *.h \
+                         *.hh \
+                         *.hpp \
+                         *.c \
+                         *.cc \
+                         *.cpp \
+                         *.txt
+EXAMPLE_RECURSIVE      = YES
+IMAGE_PATH             =
+INPUT_FILTER           =
+FILTER_PATTERNS        =
+FILTER_SOURCE_FILES    = NO
+FILTER_SOURCE_PATTERNS =
+USE_MDFILE_AS_MAINPAGE =
+FORTRAN_COMMENT_AFTER  = 72
+#---------------------------------------------------------------------------
+# Configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = YES
+STRIP_CODE_COMMENTS    = NO
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS        = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+#---------------------------------------------------------------------------
+# Configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX     = YES
+IGNORE_PREFIX          =
+#---------------------------------------------------------------------------
+# Configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            =
+HTML_FOOTER            =
+HTML_STYLESHEET        =
+HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_FILES       =
+HTML_COLORSTYLE        = LIGHT
+HTML_COLORSTYLE_HUE    = 220
+HTML_COLORSTYLE_SAT    = 100
+HTML_COLORSTYLE_GAMMA  = 80
+HTML_DYNAMIC_MENUS     = YES
+HTML_DYNAMIC_SECTIONS  = YES
+HTML_CODE_FOLDING      = YES
+HTML_INDEX_NUM_ENTRIES = 1000
+GENERATE_DOCSET        = NO
+DOCSET_FEEDNAME        = "Doxygen generated docs"
+DOCSET_FEEDURL         =
+DOCSET_BUNDLE_ID       = org.doxygen.rocprofiler
+DOCSET_PUBLISHER_ID    = org.doxygen.amd
+DOCSET_PUBLISHER_NAME  = "Advanced Micro Devices, Inc."
+GENERATE_HTMLHELP      = NO
+CHM_FILE               =
+HHC_LOCATION           =
+GENERATE_CHI           = NO
+CHM_INDEX_ENCODING     =
+BINARY_TOC             = NO
+TOC_EXPAND             = YES
+SITEMAP_URL            =
+GENERATE_QHP           = NO
+QCH_FILE               =
+QHP_NAMESPACE          =
+QHP_VIRTUAL_FOLDER     = doxy
+QHP_CUST_FILTER_NAME   =
+QHP_CUST_FILTER_ATTRS  =
+QHP_SECT_FILTER_ATTRS  =
+QHG_LOCATION           =
+GENERATE_ECLIPSEHELP   = NO
+ECLIPSE_DOC_ID         = org.doxygen.rocprofiler
+DISABLE_INDEX          = NO
+GENERATE_TREEVIEW      = NO
+FULL_SIDEBAR           = NO
+ENUM_VALUES_PER_LINE   = 1
+TREEVIEW_WIDTH         = 300
+EXT_LINKS_IN_WINDOW    = YES
+OBFUSCATE_EMAILS       = YES
+HTML_FORMULA_FORMAT    = png
+FORMULA_FONTSIZE       = 12
+FORMULA_MACROFILE      =
+USE_MATHJAX            = NO
+MATHJAX_VERSION        = MathJax_2
+MATHJAX_FORMAT         = HTML-CSS
+MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
+MATHJAX_EXTENSIONS     =
+MATHJAX_CODEFILE       =
+SEARCHENGINE           = NO
+SERVER_BASED_SEARCH    = NO
+EXTERNAL_SEARCH        = NO
+SEARCHENGINE_URL       =
+SEARCHDATA_FILE        = searchdata.xml
+EXTERNAL_SEARCH_ID     =
+EXTRA_SEARCH_MAPPINGS  =
+#---------------------------------------------------------------------------
+# Configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+LATEX_MAKEINDEX_CMD    = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             =
+EXTRA_PACKAGES         = float
+LATEX_HEADER           =
+LATEX_FOOTER           =
+LATEX_EXTRA_STYLESHEET =
+LATEX_EXTRA_FILES      =
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
+LATEX_BATCHMODE        = YES
+LATEX_HIDE_INDICES     = NO
+LATEX_BIB_STYLE        = plain
+LATEX_EMOJI_DIRECTORY  =
+#---------------------------------------------------------------------------
+# Configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    =
+RTF_EXTENSIONS_FILE    =
+#---------------------------------------------------------------------------
+# Configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_SUBDIR             =
+MAN_LINKS              = YES
+#---------------------------------------------------------------------------
+# Configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+XML_NS_MEMB_FILE_SCOPE = YES
+#---------------------------------------------------------------------------
+# Configuration options related to the DOCBOOK output
+#---------------------------------------------------------------------------
+GENERATE_DOCBOOK       = NO
+DOCBOOK_OUTPUT         = docbook
+#---------------------------------------------------------------------------
+# Configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF   = NO
+#---------------------------------------------------------------------------
+# Configuration options related to Sqlite3 output
+#---------------------------------------------------------------------------
+GENERATE_SQLITE3       = NO
+SQLITE3_OUTPUT         = sqlite3
+SQLITE3_RECREATE_DB    = YES
+#---------------------------------------------------------------------------
+# Configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX =
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = NO
+INCLUDE_PATH           = @SOURCE_DIR@/source/include
+INCLUDE_FILE_PATTERNS  = *.h \
+                         *.hpp
+PREDEFINED             = "ROCTX_API=" \
+                         "ROCTX_EXPORT=" \
+                         "ROCTX_IMPORT=" \
+                         "ROCTX_NONNULL(...)=" \
+                         "ROCTX_PUBLIC_API=" \
+                         "ROCTX_HIDDEN_API=" \
+                         "ROCTX_EXPORT_DECORATOR=" \
+                         "ROCTX_IMPORT_DECORATOR=" \
+                         "ROCTX_HANDLE_LITERAL=" \
+                         "ROCTX_EXTERN_C_INIT=" \
+                         "ROCTX_EXTERN_C_FINI=" \
+                         "__attribute__(x)=" \
+                         "__declspec(x)=" \
+                         "size_t=unsigned long" \
+                         "uintptr_t=unsigned long" \
+                         "DOXYGEN_SHOULD_SKIP_THIS=1"
+EXPAND_AS_DEFINED      =
+SKIP_FUNCTION_MACROS   = NO
+#---------------------------------------------------------------------------
+# Configuration options related to external references
+#---------------------------------------------------------------------------
+TAGFILES               =
+GENERATE_TAGFILE       = _doxygen/roctx/html/tagfile.xml
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+EXTERNAL_PAGES         = YES
+#---------------------------------------------------------------------------
+# Configuration options related to diagram generator tools
+#---------------------------------------------------------------------------
+HIDE_UNDOC_RELATIONS   = NO
+HAVE_DOT               = YES
+DOT_NUM_THREADS        = 0
+DOT_COMMON_ATTR        = "fontname=Helvetica,fontsize=12"
+DOT_EDGE_ATTR          = "labelfontname=Helvetica,labelfontsize=12"
+DOT_NODE_ATTR          = "shape=box,height=0.2,width=0.4"
+DOT_FONTPATH           =
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = YES
+UML_LIMIT_NUM_FIELDS   = 10
+DOT_UML_DETAILS        = YES
+DOT_WRAP_THRESHOLD     = 17
+TEMPLATE_RELATIONS     = YES
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = YES
+CALLER_GRAPH           = YES
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DIR_GRAPH_MAX_DEPTH    = 1
+DOT_IMAGE_FORMAT       = svg
+INTERACTIVE_SVG        = YES
+DOT_PATH               = @DOT_EXECUTABLE@
+DOTFILE_DIRS           =
+DIA_PATH               =
+DIAFILE_DIRS           =
+PLANTUML_JAR_PATH      =
+PLANTUML_CFG_FILE      =
+PLANTUML_INCLUDE_PATH  =
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_MULTI_TARGETS      = YES
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
+MSCGEN_TOOL            =
+MSCFILE_DIRS           =