diff --git a/.gitignore b/.gitignore index 0d3c0c6f..9a281c10 100644 --- a/.gitignore +++ b/.gitignore @@ -1,12 +1,10 @@ ### Build dirs ### build/ +/docs/_build/ ### Docs dirs ### -doc/html/ -doc/xml/ -doc/latex/ -doc/*.tag +/docs/docBin/ # Created by https://www.gitignore.io/api/c++,cmake @@ -51,6 +49,7 @@ CMakeFiles CMakeScripts Testing Makefile +!/docs/Makefile cmake_install.cmake install_manifest.txt compile_commands.json diff --git a/.jenkins/staticanalysis.groovy b/.jenkins/staticanalysis.groovy new file mode 100644 index 00000000..f74c3cf7 --- /dev/null +++ b/.jenkins/staticanalysis.groovy @@ -0,0 +1,68 @@ +#!/usr/bin/env groovy +// This shared library is available at https://github.com/ROCmSoftwarePlatform/rocJENKINS/ +@Library('rocJenkins@pong') _ + +// This is file for internal AMD use. +// If you are interested in running your own Jenkins, please raise a github issue for assistance. + +import com.amd.project.* +import com.amd.docker.* +import java.nio.file.Path + +def runCompileCommand(platform, project, jobName, boolean debug=false) +{ + project.paths.construct_build_prefix() + + def command = """#!/usr/bin/env bash + set -x + ${project.paths.project_build_prefix}/docs/run_doc.sh + """ + + try + { + platform.runCommand(this, command) + } + catch(e) + { + throw e + } + + publishHTML([allowMissing: false, + alwaysLinkToLastBuild: false, + keepAll: false, + reportDir: "${project.paths.project_build_prefix}/docs/_build/html", + reportFiles: "index.html", + reportName: "Documentation", + reportTitles: "Documentation"]) +} + +def runCI = +{ + nodeDetails, jobName-> + + def prj = new rocProject('hipCUB', 'StaticAnalysis') + + // Define test architectures, optional rocm version argument is available + def nodes = new dockerNodes(nodeDetails, jobName, prj) + + boolean formatCheck = false + boolean staticAnalysis = true + + def compileCommand = + { + platform, project-> + + runCompileCommand(platform, project, jobName, false) + } + + buildProject(prj , formatCheck, nodes.dockerArray, compileCommand, null, null, staticAnalysis) +} + +ci: { + String urlJobName = auxiliary.getTopJobName(env.BUILD_URL) + + properties(auxiliary.addCommonProperties([pipelineTriggers([cron('0 1 * * 6')])])) + stage(urlJobName) { + runCI([ubuntu18:['any']], urlJobName) + } +} diff --git a/LICENSE.txt b/LICENSE.txt index 48703547..c284d2bd 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,6 +1,6 @@ Copyright (c) 2010-2011, Duane Merrill. All rights reserved. Copyright (c) 2011-2018, NVIDIA CORPORATION. All rights reserved. -Modifications Copyright (c) 2019, Advanced Micro Devices, Inc. All rights reserved. +Modifications Copyright (c) 2019-2021, Advanced Micro Devices, Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/README.md b/README.md index 50a1eff3..a7af46c9 100644 --- a/README.md +++ b/README.md @@ -158,13 +158,13 @@ cd hipCUB; cd build ## Documentation ```shell -# go to hipCUB doc directory -cd hipCUB; cd doc +# go to hipCUB docs directory +cd hipCUB; cd docs -# run doxygen -doxygen Doxyfile +# run doxygen and sphinx +./run_docs.sh -# open html/index.html +# open docBin/html/index.html ``` diff --git a/doc/Doxyfile b/docs/Doxyfile similarity index 98% rename from doc/Doxyfile rename to docs/Doxyfile index 64754f16..5e85260a 100644 --- a/doc/Doxyfile +++ b/docs/Doxyfile @@ -58,7 +58,7 @@ PROJECT_LOGO = # entered, it will be relative to the location where doxygen was started. If # left blank the current directory will be used. -OUTPUT_DIRECTORY = +OUTPUT_DIRECTORY = docBin # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and @@ -152,7 +152,7 @@ FULL_PATH_NAMES = YES # will be relative from the directory where doxygen is started. # This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = +STRIP_FROM_PATH = ../hipcub/include/ # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -770,8 +770,22 @@ WARN_LOGFILE = # directories like /usr/src/myproject. Separate the files or directories with # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. - -INPUT = mainpage.dox +#mainpage.dox \ +INPUT = ../hipcub/include/hipcub \ + ../hipcub/include/hipcub/device \ + ../hipcub/include/hipcub/iterator \ + ../hipcub/include/hipcub/thread \ + ../hipcub/include/hipcub/warp \ + ../hipcub/include/hipcub/block \ + ../hipcub/include/hipcub/backend \ + ../hipcub/include/hipcub/backend/cub \ + ../hipcub/include/hipcub/backend/cub/device \ + ../hipcub/include/hipcub/backend/rocprim \ + ../hipcub/include/hipcub/backend/rocprim/device \ + ../hipcub/include/hipcub/backend/rocprim/iterator \ + ../hipcub/include/hipcub/backend/rocprim/thread \ + ../hipcub/include/hipcub/backend/rocprim/warp \ + ../hipcub/include/hipcub/backend/rocprim/block # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses @@ -1884,7 +1898,7 @@ MAN_LINKS = NO # captures the structure of the code including all documentation. # The default value is: NO. -GENERATE_XML = yes +GENERATE_XML = YES # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -1997,7 +2011,7 @@ ENABLE_PREPROCESSING = YES # The default value is: NO. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -MACRO_EXPANSION = NO +MACRO_EXPANSION = YES # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then # the macro expansion is limited to the macros specified with the PREDEFINED and @@ -2019,7 +2033,7 @@ SEARCH_INCLUDES = YES # preprocessor. # This tag requires that the tag SEARCH_INCLUDES is set to YES. -INCLUDE_PATH = +INCLUDE_PATH = ../hipcub/include/hipcub/ # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the @@ -2037,7 +2051,9 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = "DOXYGEN_SHOULD_SKIP_THIS=1" +PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS=1 \ + __HIP_PLATFORM_HCC__=1 \ + HIPCUB_DEVICE=__device__ # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The @@ -2056,7 +2072,7 @@ EXPAND_AS_DEFINED = # The default value is: YES. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -SKIP_FUNCTION_MACROS = YES +SKIP_FUNCTION_MACROS = NO #--------------------------------------------------------------------------- # Configuration options related to external references @@ -2172,7 +2188,7 @@ DOT_NUM_THREADS = 0 # The default value is: Helvetica. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_FONTNAME = FreeSans +DOT_FONTNAME = # The DOT_FONTSIZE tag can be used to set the size (in points) of the font of # dot graphs. diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..ff9e5d16 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,24 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = hipCUB +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 clean + +# 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) + +clean: + rm -rf docBin/ api/ + @$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..73c78a1a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,204 @@ +# -*- coding: utf-8 -*- +# +# hipCUB documentation build configuration file, created by +# sphinx-quickstart on Mon Jan 8 16:34:42 2018. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# 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 +# sys.path.insert(0, os.path.abspath('.')) + +import os +import sys +import subprocess + +read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True' + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.mathjax', 'breathe', 'exhale'] +breathe_projects = { "hipCUB": "./docBin/xml" } +breathe_default_project = "hipCUB" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'hipCUB' +copyright = u'2010-2011, Duane Merrill; 2011-2018, NVIDIA CORPORATION; Modifications Copyright 2019-2021 Advanced Micro Devices' +author = u'Advanced Micro Devices' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'2.10.9' +# The full version, including alpha/beta/rc tags. +release = u'2.10.9' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- 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 = 'alabaster' + +if read_the_docs_build: + html_theme = 'default' +else: + import sphinx_rtd_theme + html_theme = "sphinx_rtd_theme" + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# 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_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +# html_sidebars = { +# '**': [ +# 'relations.html', # needs 'show_related': True theme option to display +# 'searchbox.html', +# ] +# } + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'hipCUBdoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'hipCUB.tex', u'hipCUB Documentation', + u'Advanced Micro Devices', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'hipCUB', u'hipCUB Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'hipCUB', u'hipCUB Documentation', + author, 'hipCUB', 'Reusable software components for rocm developers.', + 'Miscellaneous'), +] + + + +# Setup the exhale extension +exhale_args = { + # These arguments are required + "containmentFolder": "./api", + "rootFileName": "library_root.rst", + "rootFileTitle": "Library API", + "doxygenStripFromPath": "..", + # Suggested optional arguments + "createTreeView": True, + # TIP: if using the sphinx-bootstrap-theme, you need + # "treeViewIsBootstrap": True, + "exhaleExecutesDoxygen": True, + "exhaleUseDoxyfile": True +} + +# Tell sphinx what the primary language being documented is. +primary_domain = 'cpp' +cpp_id_attributes = ["__global__", "__device__", "__host__"] +cpp_paren_attributes = ["__declspec"] + +# Tell sphinx what the pygments highlight language should be. +highlight_language = 'cpp' diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..b303e27c --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,17 @@ +.. hipCUBs documentation master file + +Welcome to hipCUB's documentation! +================================== + +.. toctree:: + :maxdepth: 3 + :caption: Contents: + + introduction + api/library_root + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/docs/introduction.rst b/docs/introduction.rst new file mode 100644 index 00000000..2a3ca9e0 --- /dev/null +++ b/docs/introduction.rst @@ -0,0 +1,56 @@ + +************* +Introduction +************* + +.. toctree:: + :maxdepth: 4 + :caption: Contents: + +Overview +================== + +hipCUB is a thin wrapper library on top of rocPRIM or CUB. It enables developers to port project +using CUB library to the `HIP `_ layer and to run them +on AMD hardware. In the `ROCm `_ environment, hipCUB uses +rocPRIM library as the backend, however, on CUDA platforms it uses CUB instead. + +- When using hipCUB you should only include ```` header. +- When rocPRIM is used as backend ``HIPCUB_ROCPRIM_API`` is defined. +- When CUB is used as backend ``HIPCUB_CUB_API`` is defined. +- Backends are automaticaly selected based on platform detected by HIP layer + (``__HIP_PLATFORM_HCC__``, ``__HIP_PLATFORM_NVCC__``). + +rocPRIM backend +==================================== + +hipCUB with rocPRIM backend may not support all function and features CUB has because of the +differences between ROCm (HIP) platform and CUDA platform. + +Not-supported features and differences: + +- Functions, classes and macros which are not in the public API or not documented are not + supported. +- Device-wide primitives can't be called from kernels (dynamic parallelism is not supported in HIP + on ROCm). +- ``DeviceSpmv`` is not supported. +- Fancy iterators: ``CacheModifiedInputIterator``, ``CacheModifiedOutputIterator``, and + ``TexRefInputIterator`` are not supported. +- Thread I/O: + + - ``CacheLoadModifier``, ``CacheStoreModifier`` cache modifiers are not supported. + - ``ThreadLoad``, ``ThreadStore`` functions are not supported. +- Storage management and debug functions: + + - ``Debug``, ``PtxVersion``, ``SmVersion`` functions and ``CubDebug``, ``CubDebugExit``, + ``_CubLog`` macros are not supported. +- Intrinsics: + + - ``ThreadExit``, ``ThreadTrap`` - not supported. + - Warp thread masks (when used) are 64-bit unsigned integers. + - ``member_mask`` input argument is ignored in ``WARP_*`` functions. + - Arguments ``first_lane``, ``last_lane``, and ``member_mask`` are ignored in ``Shuffle*`` + functions. +- Utilities: + + - ``SwizzleScanOp``, ``ReduceBySegmentOp``, ``ReduceByKeyOp``, ``CastOp`` - not supported. diff --git a/doc/mainpage.dox b/docs/mainpage.dox similarity index 100% rename from doc/mainpage.dox rename to docs/mainpage.dox diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..71440551 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +breathe +exhale diff --git a/docs/run_doc.sh b/docs/run_doc.sh new file mode 100755 index 00000000..c173bd9e --- /dev/null +++ b/docs/run_doc.sh @@ -0,0 +1,11 @@ +#!/bin/bash + +set -eu + +# Make this directory the PWD +cd "$(dirname "${BASH_SOURCE[0]}")" + +# Build sphinx docs (Exhale will automatically run Doxygen) +make clean +make html +make latexpdf