diff --git a/sycl/doc/doxygen.cfg.in b/sycl/doc/doxygen.cfg.in index a3d568260431e..611b99c5ff3ee 100644 --- a/sycl/doc/doxygen.cfg.in +++ b/sycl/doc/doxygen.cfg.in @@ -171,7 +171,9 @@ STRIP_FROM_PATH = @abs_srcdir@/.. # specify the list of include paths that are normally passed to the compiler # using the -I flag. -STRIP_FROM_INC_PATH = @abs_srcdir@/../include +STRIP_FROM_INC_PATH = @abs_srcdir@/../include \ + @abs_srcdir@/../source \ + @abs_srcdir@/../plugins # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but # less readable) file names. This can be useful is your file systems doesn't @@ -791,7 +793,8 @@ WARN_LOGFILE = # Note: If this tag is empty the current directory is searched. INPUT = @abs_srcdir@/../include \ - @abs_srcdir@/../source + @abs_srcdir@/../source \ + @abs_srcdir@/../plugins # 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 @@ -1062,7 +1065,7 @@ SOURCE_TOOLTIPS = YES # The default value is: NO. # This tag requires that the tag SOURCE_BROWSER is set to YES. -USE_HTAGS = YES +USE_HTAGS = NO # If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a # verbatim copy of the header file for each class for which an include is diff --git a/sycl/include/CL/sycl/detail/pi.h b/sycl/include/CL/sycl/detail/pi.h index 6a2a051c4958e..29533d67a767a 100644 --- a/sycl/include/CL/sycl/detail/pi.h +++ b/sycl/include/CL/sycl/detail/pi.h @@ -5,13 +5,20 @@ // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception // //===----------------------------------------------------------------------===// -// -// This is the definition of a generic offload Plugin Interface (PI), which is -// used by the SYCL implementation to connect to multiple device back-ends, -// e.g. to OpenCL. The interface is intentionally kept C-only for the -// purpose of having full flexibility and interoperability with different -// environments. -// + +/// \defgroup sycl_pi The Plugin Interface +// TODO: link to sphinx page + +/// \file Main Plugin Interface header file. +/// +/// This is the definition of a generic offload Plugin Interface (PI), which is +/// used by the SYCL implementation to connect to multiple device back-ends, +/// e.g. to OpenCL. The interface is intentionally kept C-only for the +/// purpose of having full flexibility and interoperability with different +/// environments. +/// +/// \ingroup sycl_pi + #ifndef _PI_H_ #define _PI_H_ diff --git a/sycl/include/CL/sycl/detail/pi.hpp b/sycl/include/CL/sycl/detail/pi.hpp index 2ecf2aebdc679..f5404a4afc9a1 100644 --- a/sycl/include/CL/sycl/detail/pi.hpp +++ b/sycl/include/CL/sycl/detail/pi.hpp @@ -6,8 +6,11 @@ // //===----------------------------------------------------------------------===// -// C++ wrapper of extern "C" PI interfaces -// +/// \file pi.hpp +/// C++ wrapper of extern "C" PI interfaces +/// +/// \ingroup sycl_pi + #pragma once #include diff --git a/sycl/plugins/cuda/pi_cuda.cpp b/sycl/plugins/cuda/pi_cuda.cpp index 186310287f212..c03fd7e56eaa3 100644 --- a/sycl/plugins/cuda/pi_cuda.cpp +++ b/sycl/plugins/cuda/pi_cuda.cpp @@ -6,6 +6,11 @@ // //===----------------------------------------------------------------------===// +/// \file pi_cuda.cpp +/// Implementation of CUDA Plugin. +/// +/// \ingroup sycl_pi_cuda + #include #include #include diff --git a/sycl/plugins/cuda/pi_cuda.hpp b/sycl/plugins/cuda/pi_cuda.hpp index fad29836ca0ed..fe0fda38bd3c7 100644 --- a/sycl/plugins/cuda/pi_cuda.hpp +++ b/sycl/plugins/cuda/pi_cuda.hpp @@ -6,9 +6,14 @@ // //===----------------------------------------------------------------------===// -/// This source is the definition of the SYCL Plugin Interface -/// (PI). It is the interface between the device-agnostic SYCL runtime layer -/// and underlying "native" runtimes such as OpenCL. +/// \defgroup sycl_pi_cuda CUDA Plugin +/// \ingroup sycl_pi + +/// \file pi_cuda.hpp +/// Definition of CUDA Plugin. It is the interface between the device-agnostic +/// SYCL runtime layer and underlying CUDA runtime. +/// +/// \ingroup sycl_pi_cuda #ifndef PI_CUDA_HPP #define PI_CUDA_HPP diff --git a/sycl/plugins/opencl/pi_opencl.cpp b/sycl/plugins/opencl/pi_opencl.cpp index 674a4e275c5fd..846d2b60a3708 100644 --- a/sycl/plugins/opencl/pi_opencl.cpp +++ b/sycl/plugins/opencl/pi_opencl.cpp @@ -5,6 +5,16 @@ // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception // //===----------------------------------------------------------------------===// + +/// \defgroup sycl_pi_ocl OpenCL Plugin +/// \ingroup sycl_pi + +/// \file pi_opencl.cpp +/// Implementation of OpenCL Plugin. It is the interface between device-agnostic +/// SYCL runtime layer and underlying OpenCL runtime. +/// +/// \ingroup sycl_pi_ocl + #include "CL/opencl.h" #include diff --git a/sycl/source/detail/pi.cpp b/sycl/source/detail/pi.cpp index 9b0959063fbe5..3c99a4dc0532d 100644 --- a/sycl/source/detail/pi.cpp +++ b/sycl/source/detail/pi.cpp @@ -5,6 +5,12 @@ // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception // //===----------------------------------------------------------------------===// + +/// \file pi.cpp +/// Implementation of C++ wrappers for PI interface. +/// +/// \ingroup sycl_pi + #include #include #include diff --git a/sycl/source/detail/plugin.hpp b/sycl/source/detail/plugin.hpp index e5451dfa79a37..dd67409eb3480 100644 --- a/sycl/source/detail/plugin.hpp +++ b/sycl/source/detail/plugin.hpp @@ -15,6 +15,10 @@ __SYCL_INLINE_NAMESPACE(cl) { namespace sycl { namespace detail { +/// The plugin class provides a unified interface to the underlying low-level +/// runtimes for the device-agnostic SYCL runtime. +/// +/// \ingroup sycl_pi class plugin { public: plugin() = delete; @@ -25,21 +29,24 @@ class plugin { ~plugin() = default; - // Utility function to check return from PI calls. - // Throws if pi_result is not a PI_SUCCESS. - // Exception - The type of exception to throw if PiResult of a call is not - // PI_SUCCESS. Default value is cl::sycl::runtime_error. + /// Checks return value from PI calls. + /// + /// \throw Exception if pi_result is not a PI_SUCCESS. template void checkPiResult(RT::PiResult pi_result) const { CHECK_OCL_CODE_THROW(pi_result, Exception); } - // Call the PiApi, trace the call and return the result. - // To check the result use checkPiResult. - // Usage: - // PiResult Err = plugin.call(Args); - // Plugin.checkPiResult(Err); <- Checks Result and throws a runtime_error - // exception. + /// Calls the PiApi, traces the call, and returns the result. + /// + /// Usage: + /// \code{cpp} + /// PiResult Err = plugin.call(Args); + /// Plugin.checkPiResult(Err); // Checks Result and throws a runtime_error + /// // exception. + /// \endcode + /// + /// \sa plugin::checkPiResult template RT::PiResult call_nocheck(ArgsT... Args) const { RT::PiFuncInfo PiCallInfo; @@ -56,8 +63,9 @@ class plugin { return R; } - // Call the API, trace the call, check the result and throw - // a runtime_error Exception + /// Calls the API, traces the call, checks the result + /// + /// \throw cl::sycl::runtime_exception if the call was not successful. template void call(ArgsT... Args) const { RT::PiResult Err = call_nocheck(Args...);