From 04ace57589954394e9e1e5cfc3ff93b9742b18a3 Mon Sep 17 00:00:00 2001 From: "Bhardwaj, Gopesh" Date: Wed, 22 Jan 2025 23:04:21 +0530 Subject: [PATCH] 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 [ROCm/rocprofiler-sdk commit: 73e7f8cfb1e7cb7cb2012d365ef097f7f71f0a79] --- .../.github/workflows/docs.yml | 23 +- projects/rocprofiler-sdk/.readthedocs.yaml | 21 +- .../source/docs/CMakeLists.txt | 5 +- .../rocprofiler-sdk/source/docs/_toc.yml.in | 6 +- projects/rocprofiler-sdk/source/docs/conf.py | 2 +- .../source/docs/generate-doxyfile.cmake | 3 + .../rocprofiler-sdk/source/docs/index.rst | 3 +- .../source/docs/rocprofiler-sdk-roctx.dox.in | 402 ++++++++++++++++++ .../source/docs/rocprofiler-sdk.dox.in | 4 +- .../include/rocprofiler-sdk-roctx/roctx.h | 50 ++- .../include/rocprofiler-sdk/rocprofiler.h | 28 ++ .../source/scripts/update-docs.sh | 6 +- .../source/scripts/update-doxygen.sh | 8 +- 13 files changed, 529 insertions(+), 32 deletions(-) create mode 100644 projects/rocprofiler-sdk/source/docs/rocprofiler-sdk-roctx.dox.in diff --git a/projects/rocprofiler-sdk/.github/workflows/docs.yml b/projects/rocprofiler-sdk/.github/workflows/docs.yml index f061840014..900f85feec 100644 --- a/projects/rocprofiler-sdk/.github/workflows/docs.yml +++ b/projects/rocprofiler-sdk/.github/workflows/docs.yml @@ -48,7 +48,21 @@ jobs: uses: actions/configure-pages@v5 - name: Create Docs Directory run: - mkdir -p docs + mkdir -p docs/_doxygen/rocprofiler-sdk + mkdir -p docs/_doxygen/roctx + - name: Install Conda environment + shell: bash -el {0} + working-directory: source/docs + run: | + conda env create -n rocprofiler-docs -f environment.yml + - name: Install documentation dependencies + timeout-minutes: 10 + shell: bash + run: | + sudo apt-get update + sudo apt-get install -y doxygen graphviz + sudo python3 -m pip install sphinx + sudo python3 -m pip install doxysphinx rocm-docs-core - name: Build Docs shell: bash -el {0} working-directory: source/docs @@ -59,7 +73,7 @@ jobs: conda env create -n rocprofiler-docs -f environment.yml source activate conda activate rocprofiler-docs - ../scripts/update-docs.sh + sudo ../scripts/update-docs.sh - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: @@ -88,7 +102,10 @@ jobs: uses: actions/checkout@v4 with: submodules: true - + - name: Create Docs Directory + run: + mkdir -p source/docs/_doxygen/rocprofiler-sdk + mkdir -p source/docs/_doxygen/roctx - name: Install requirements timeout-minutes: 10 shell: bash diff --git a/projects/rocprofiler-sdk/.readthedocs.yaml b/projects/rocprofiler-sdk/.readthedocs.yaml index 2f78e0c08c..de8728653e 100644 --- a/projects/rocprofiler-sdk/.readthedocs.yaml +++ b/projects/rocprofiler-sdk/.readthedocs.yaml @@ -3,19 +3,22 @@ version: 2 -sphinx: - configuration: source/docs/conf.py +build: + os: ubuntu-22.04 + tools: + python: "mambaforge-22.9" + jobs: + post_create_environment: + - ./source/scripts/update-doxygen.sh -formats: [htmlzip, pdf, epub] +conda: + environment: source/docs/environment.yml python: install: - requirements: source/docs/sphinx/requirements.txt -build: - os: ubuntu-22.04 - tools: - python: "mambaforge-22.9" +sphinx: + configuration: source/docs/conf.py -conda: - environment: source/docs/environment.yml +formats: [htmlzip, pdf, epub] diff --git a/projects/rocprofiler-sdk/source/docs/CMakeLists.txt b/projects/rocprofiler-sdk/source/docs/CMakeLists.txt index 2f08ab8633..55eff9f110 100644 --- a/projects/rocprofiler-sdk/source/docs/CMakeLists.txt +++ b/projects/rocprofiler-sdk/source/docs/CMakeLists.txt @@ -115,9 +115,10 @@ cd \${WORK_DIR} cmake -DSOURCE_DIR=\${SOURCE_DIR} -P \${WORK_DIR}/generate-doxyfile.cmake doxygen rocprofiler-sdk.dox -doxygen rocprofiler-sdk.dox +doxygen rocprofiler-sdk-roctx.dox -doxysphinx build \${WORK_DIR} \${WORK_DIR}/_build/html \${WORK_DIR}/_doxygen/html +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=\"-W --keep-going ${DOCS_BUILD_JOBS} -n\" diff --git a/projects/rocprofiler-sdk/source/docs/_toc.yml.in b/projects/rocprofiler-sdk/source/docs/_toc.yml.in index b43bae6e0a..b51bb031b8 100644 --- a/projects/rocprofiler-sdk/source/docs/_toc.yml.in +++ b/projects/rocprofiler-sdk/source/docs/_toc.yml.in @@ -27,8 +27,10 @@ subtrees: title: PC sampling - file: api-reference/tool_library title: Tool library - - file: _doxygen/html/index - title: API library + - file: _doxygen/rocprofiler-sdk/html/index + title: ROCprofiler-SDK API library + - file: _doxygen/roctx/html/index + title: ROCTx API library - caption: Conceptual entries: - file: conceptual/comparing-with-legacy-tools diff --git a/projects/rocprofiler-sdk/source/docs/conf.py b/projects/rocprofiler-sdk/source/docs/conf.py index f1c6a01c7a..bc3856f826 100644 --- a/projects/rocprofiler-sdk/source/docs/conf.py +++ b/projects/rocprofiler-sdk/source/docs/conf.py @@ -78,7 +78,7 @@ doxygen_root = "." doxysphinx_enabled = True doxygen_project = { "name": "rocprofiler-sdk", - "path": "_doxygen/xml", + "path": "_doxygen", } doxyfile = "rocprofiler-sdk.dox" diff --git a/projects/rocprofiler-sdk/source/docs/generate-doxyfile.cmake b/projects/rocprofiler-sdk/source/docs/generate-doxyfile.cmake index 2745b2a53c..354e0a18cb 100644 --- a/projects/rocprofiler-sdk/source/docs/generate-doxyfile.cmake +++ b/projects/rocprofiler-sdk/source/docs/generate-doxyfile.cmake @@ -17,3 +17,6 @@ string(REGEX REPLACE "([0-9]+)\\.([0-9]+)\\.([0-9]+)(.*)" "\\1.\\2.\\3" 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) diff --git a/projects/rocprofiler-sdk/source/docs/index.rst b/projects/rocprofiler-sdk/source/docs/index.rst index e6c4ccfdc4..1ce413f67c 100644 --- a/projects/rocprofiler-sdk/source/docs/index.rst +++ b/projects/rocprofiler-sdk/source/docs/index.rst @@ -42,7 +42,8 @@ The documentation is structured as follows: * :doc:`Intercept table ` * :doc:`PC sampling ` * :doc:`Tool library ` - * :doc:`API library <_doxygen/html/index>` + * :doc:`ROCprofiler-SDK API library <_doxygen/rocprofiler-sdk/html/index>` + * :doc:`ROCTx API library <_doxygen/roctx/html/index>` .. grid-item-card:: Conceptual diff --git a/projects/rocprofiler-sdk/source/docs/rocprofiler-sdk-roctx.dox.in b/projects/rocprofiler-sdk/source/docs/rocprofiler-sdk-roctx.dox.in new file mode 100644 index 0000000000..a71e429852 --- /dev/null +++ b/projects/rocprofiler-sdk/source/docs/rocprofiler-sdk-roctx.dox.in @@ -0,0 +1,402 @@ +# 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 = YES +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 = YES +HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_CLASSES = YES +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 = NO +FORCE_LOCAL_INCLUDES = YES +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 = NO +WARNINGS = YES +WARN_IF_UNDOCUMENTED = YES +WARN_IF_DOC_ERROR = YES +WARN_IF_INCOMPLETE_DOC = YES +WARN_NO_PARAMDOC = YES +WARN_IF_UNDOC_ENUM_VAL = NO +WARN_AS_ERROR = NO +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 = +EXCLUDE_SYMLINKS = YES +EXCLUDE_PATTERNS = */.git/* \ + @SOURCE_DIR@/**/tests/* \ + @SOURCE_DIR@/**/scripts/* \ + @SOURCE_DIR@/**/docs/* +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" +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 +PREDEFINED = "ROCPROFILER_API=" \ + "ROCPROFILER_EXPORT=" \ + "ROCPROFILER_IMPORT=" \ + "ROCPROFILER_NONNULL(...)=" \ + "ROCPROFILER_PUBLIC_API=" \ + "ROCPROFILER_HIDDEN_API=" \ + "ROCPROFILER_EXPORT_DECORATOR=" \ + "ROCPROFILER_IMPORT_DECORATOR=" \ + "ROCPROFILER_HANDLE_LITERAL=" \ + "ROCPROFILER_EXTERN_C_INIT=" \ + "ROCPROFILER_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 = diff --git a/projects/rocprofiler-sdk/source/docs/rocprofiler-sdk.dox.in b/projects/rocprofiler-sdk/source/docs/rocprofiler-sdk.dox.in index 1f9bcdf7d9..25a90eac69 100644 --- a/projects/rocprofiler-sdk/source/docs/rocprofiler-sdk.dox.in +++ b/projects/rocprofiler-sdk/source/docs/rocprofiler-sdk.dox.in @@ -8,7 +8,7 @@ PROJECT_NAME = @PROJECT_NAME@ Developer API PROJECT_NUMBER = @ROCPROFILER_VERSION@ PROJECT_BRIEF = "ROCm Profiling API and tools" PROJECT_LOGO = -OUTPUT_DIRECTORY = _doxygen +OUTPUT_DIRECTORY = _doxygen/rocprofiler-sdk CREATE_SUBDIRS = NO CREATE_SUBDIRS_LEVEL = 8 ALLOW_UNICODE_NAMES = YES @@ -361,7 +361,7 @@ SKIP_FUNCTION_MACROS = NO # Configuration options related to external references #--------------------------------------------------------------------------- TAGFILES = -GENERATE_TAGFILE = _doxygen/html/tagfile.xml +GENERATE_TAGFILE = _doxygen/rocprofiler-sdk/html/tagfile.xml ALLEXTERNALS = NO EXTERNAL_GROUPS = YES EXTERNAL_PAGES = YES diff --git a/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-roctx/roctx.h b/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-roctx/roctx.h index 827cff12e3..b594e6de43 100644 --- a/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-roctx/roctx.h +++ b/projects/rocprofiler-sdk/source/include/rocprofiler-sdk-roctx/roctx.h @@ -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 diff --git a/projects/rocprofiler-sdk/source/include/rocprofiler-sdk/rocprofiler.h b/projects/rocprofiler-sdk/source/include/rocprofiler-sdk/rocprofiler.h index b2ddf54339..2a8990dafb 100644 --- a/projects/rocprofiler-sdk/source/include/rocprofiler-sdk/rocprofiler.h +++ b/projects/rocprofiler-sdk/source/include/rocprofiler-sdk/rocprofiler.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 #include diff --git a/projects/rocprofiler-sdk/source/scripts/update-docs.sh b/projects/rocprofiler-sdk/source/scripts/update-docs.sh index c452810657..bb3a449255 100755 --- a/projects/rocprofiler-sdk/source/scripts/update-docs.sh +++ b/projects/rocprofiler-sdk/source/scripts/update-docs.sh @@ -24,11 +24,13 @@ message "Generating rocprofiler-sdk.dox" cmake -DSOURCE_DIR=${SOURCE_DIR} -DPROJECT_NAME="Rocprofiler SDK" -P ${WORK_DIR}/generate-doxyfile.cmake message "Generating doxygen xml files" +mkdir -p _doxygen doxygen rocprofiler-sdk.dox -doxygen rocprofiler-sdk.dox +doxygen rocprofiler-sdk-roctx.dox message "Running doxysphinx" -doxysphinx build ${WORK_DIR} ${WORK_DIR}/_build/html ${WORK_DIR}/_doxygen/html +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 message "Building html documentation" make html SPHINXOPTS="--keep-going -n" diff --git a/projects/rocprofiler-sdk/source/scripts/update-doxygen.sh b/projects/rocprofiler-sdk/source/scripts/update-doxygen.sh index 6fbaf72c11..60e293658c 100755 --- a/projects/rocprofiler-sdk/source/scripts/update-doxygen.sh +++ b/projects/rocprofiler-sdk/source/scripts/update-doxygen.sh @@ -10,7 +10,11 @@ popd pushd ${WORK_DIR} cmake -DSOURCE_DIR=${SOURCE_DIR} -P generate-doxyfile.cmake -doxygen rocprofiler-sdk.dox -doxysphinx build ${WORK_DIR} ${WORK_DIR}/_build/html ${WORK_DIR}/_doxygen/html +mkdir -p _doxygen +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 popd