ROCTx Documentation (#29)

* Add roctx doc * Add roctx doxyfile input * Update links and toc * Build doxysphinx for both doxygen files * Update scripts * Generate roctx doxygen files * Change doxygen path to allow for 2 doxyfiles * Make doxygen dir for script * Call make _doxygen dir with p flag * Create _doxygen dir in workfllow * Create doc dirs for doxygen * Run update docs as sudo * Fix typo in mkdir command * Include graphviz for dot * Install dot for docs CI * Install dot as sudo due to permission denied * Install doxygen via sudo * Install doxysphinx * Add postcheckout step to RTD to config and gen doxygen docs * On RTD, update doxygen after creating env * update docs.yml * update docs.yml * fixing build-docs-from-source * Fixing build docs from source * update docs.yml * trying to fix readthedocs * trying to fix readthedocs * update docs.yml * improve mainpage documentation * update docs * clang-format fix --------- Co-authored-by: Sam Wu <22262939+samjwu@users.noreply.github.com> Co-authored-by: Madsen, Jonathan <Jonathan.Madsen@amd.com> [ROCm/rocprofiler-sdk commit: 73e7f8cfb1]
2025-01-22 11:34:21 -06:00
@@ -22,16 +22,50 @@

 #pragma once

-/** \mainpage ROCTx API Specification
+/**
+ * \file roctx.h
+ * \brief ROCTx API interface for AMD code annotation and profiling
+ *
+ * \mainpage ROCTx API Specification
 *
 * \section introduction Introduction
- * ROCTx is a library that implements the AMD code annotation API.  It provides
- * the support necessary to annotate events and code ranges in applications.
- */
-
-/**
- * \file
- * ROCTx API interface.
+ * 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 user's responsibility
 */

 #include <stddef.h>
@@ -22,6 +22,34 @@

 #pragma once

+/**
+ *
+ * \file rocprofiler.h
+ * \brief ROCProfiler-SDK API interface.
+ *
+ * \mainpage ROCProfiler-SDK API Specification
+ *
+ * \section introduction Introduction
+ * ROCprofiler-SDK is a library that implements the profiling and performance monitoring
+ * capabilities for AMD's ROCm platform. It provides a comprehensive set of APIs for:
+ *
+ * - Hardware performance counters monitoring
+ * - PC sampling for kernel execution analysis
+ * - Buffer and callback-based tracing mechanisms
+ * - Device and dispatch counting services
+ * - External correlation tracking
+ * - HIP and HSA runtime profiling support
+ *
+ * The library is designed to help developers analyze and optimize the performance
+ * of applications running on AMD GPUs. It offers both low-level hardware access
+ * and high-level profiling abstractions to accommodate different profiling needs.
+ *
+ *
+ * \section compatibility Compatibility
+ * ROCprofiler-SDK is compatible with AMD ROCm platform and supports
+ * profiling of applications using HIP and HSA runtimes.
+ */
+
 #include <stddef.h>
 #include <stdint.h>