From 54aa641fc451d8cad907ddaf503e3d971f3dffcb Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Wed, 7 Apr 2021 00:35:12 -0500 Subject: [PATCH 1/2] Various doc string updates to C APi files. --- .../helper/include/dpctl_vector_macros.h | 5 +- .../include/Support/MemOwnershipAttrs.h | 16 +----- .../include/dpctl_sycl_context_interface.h | 13 +++++ .../include/dpctl_sycl_device_interface.h | 56 ++++++++++++++++--- .../include/dpctl_sycl_device_manager.h | 11 ++-- .../dpctl_sycl_device_selector_interface.h | 3 +- dpctl-capi/include/dpctl_sycl_enum_types.h | 2 +- .../include/dpctl_sycl_event_interface.h | 6 ++ .../include/dpctl_sycl_kernel_interface.h | 7 +++ .../include/dpctl_sycl_platform_interface.h | 15 ++++- .../include/dpctl_sycl_platform_manager.h | 8 +++ .../include/dpctl_sycl_program_interface.h | 9 +++ .../include/dpctl_sycl_queue_interface.h | 41 ++++++++------ dpctl-capi/include/dpctl_sycl_queue_manager.h | 3 +- dpctl-capi/include/dpctl_sycl_types.h | 20 +++---- dpctl-capi/include/dpctl_sycl_usm_interface.h | 17 +++++- dpctl-capi/include/dpctl_vector.h | 50 ++++++++++++++--- 17 files changed, 212 insertions(+), 70 deletions(-) diff --git a/dpctl-capi/helper/include/dpctl_vector_macros.h b/dpctl-capi/helper/include/dpctl_vector_macros.h index d5c6302979..d40eb3bf0b 100644 --- a/dpctl-capi/helper/include/dpctl_vector_macros.h +++ b/dpctl-capi/helper/include/dpctl_vector_macros.h @@ -18,8 +18,9 @@ // //===----------------------------------------------------------------------===// /// -/// \file These macros are used in dpctl_vector_templ.cpp. They help build the -/// function signatures for the functions defined in dpctl_vector_templ.cpp. +/// \file +/// A set of macros used inside dpctl_vector_templ.cpp. The macros help build +/// the function signatures for the functions defined in dpctl_vector_templ.cpp. /// //===----------------------------------------------------------------------===// diff --git a/dpctl-capi/include/Support/MemOwnershipAttrs.h b/dpctl-capi/include/Support/MemOwnershipAttrs.h index 1c01dbf087..6d680ae214 100644 --- a/dpctl-capi/include/Support/MemOwnershipAttrs.h +++ b/dpctl-capi/include/Support/MemOwnershipAttrs.h @@ -21,7 +21,7 @@ /// \file /// This file defines a group of macros that serve as attributes indicating the /// type of ownership of a pointer. The macros are modeled after similar -/// attributes defines in Integer Set Library (isl) and serve the purpose of +/// attributes defined in Integer Set Library (isl) and serve the purpose of /// helping a programmer understand the semantics of a dpctl function. /// //===----------------------------------------------------------------------===// @@ -29,12 +29,6 @@ #pragma once /** - * @defgroup MEM_MGMT_ATTR_MACROS Memory management attributes. - * - * @{ - */ - -/*! * @def __dpctl_give * @brief The __dpctl_give attribute indicates that a new object is returned and * the caller now owns the object. @@ -44,7 +38,6 @@ * free the object, he/she should make sure to use it exactly once as a value * for a __dpctl_take argument. However, the user is free to use the object as * he/she likes as a value to __dpctl_keep arguments. - * */ #ifndef __dpctl_give #define __dpctl_give @@ -60,27 +53,22 @@ * function. If the pointer annotated with __dpctl_take is NULL then it is * treated as an error, since it may prevent the normal behavior of the * function. - * */ #ifndef __dpctl_take #define __dpctl_take #endif +#ifndef __dpctl_keep /*! * @def __dpctl_keep * @brief The __dpctl_keep attribute indicates that the function only uses the * object and does not destroy it before returning. - * */ -#ifndef __dpctl_keep #define __dpctl_keep #endif /*! * @def __dpctl_null * @brief The __dpctl_null attribute indicates that a NULL value is returned. - * */ #ifndef __dpctl_null #define __dpctl_null #endif - -/** @} */ diff --git a/dpctl-capi/include/dpctl_sycl_context_interface.h b/dpctl-capi/include/dpctl_sycl_context_interface.h index 4920964359..b750084e3f 100644 --- a/dpctl-capi/include/dpctl_sycl_context_interface.h +++ b/dpctl-capi/include/dpctl_sycl_context_interface.h @@ -37,6 +37,10 @@ DPCTL_C_EXTERN_C_BEGIN +/** + * @defgroup ContextInterface Context class C wrapper + */ + /*! * @brief Constructs a new SYCL context for the given SYCL device using the * optional async error handler and properties bit flags. @@ -49,6 +53,7 @@ DPCTL_C_EXTERN_C_BEGIN * context properties. Currently, dpctl does not use * this argument. * @return A new opaque pointer wrapping a SYCL context. + * @ingroup ContextInterface */ DPCTL_API __dpctl_give DPCTLSyclContextRef @@ -69,6 +74,7 @@ DPCTLContext_Create(__dpctl_keep const DPCTLSyclDeviceRef DRef, * context properties. Currently, dpctl does not use * this argument. * @return A new opaque pointer wrapping a SYCL context. + * @ingroup ContextInterface */ DPCTL_API __dpctl_give DPCTLSyclContextRef @@ -83,6 +89,7 @@ DPCTLContext_CreateFromDevices(__dpctl_keep const DPCTLDeviceVectorRef DVRef, * @param CtxRef1 First opaque pointer to the sycl context. * @param CtxRef2 Second opaque pointer to the sycl context. * @return True if the underlying sycl::context are same, false otherwise. + * @ingroup ContextInterface */ DPCTL_API bool DPCTLContext_AreEq(__dpctl_keep const DPCTLSyclContextRef CtxRef1, @@ -94,6 +101,7 @@ bool DPCTLContext_AreEq(__dpctl_keep const DPCTLSyclContextRef CtxRef1, * @param CRef DPCTLSyclContextRef object to be copied. * @return A new DPCTLSyclContextRef created by copying the passed in * DPCTLSyclContextRef object. + * @ingroup ContextInterface */ DPCTL_API __dpctl_give DPCTLSyclContextRef @@ -105,6 +113,7 @@ DPCTLContext_Copy(__dpctl_keep const DPCTLSyclContextRef CRef); * * @param CRef DPCTLSyclContexRef object to query. * @return A positive count on success or zero on error. + * @ingroup ContextInterface */ DPCTL_API size_t DPCTLContext_DeviceCount(__dpctl_keep const DPCTLSyclContextRef CRef); @@ -115,6 +124,7 @@ size_t DPCTLContext_DeviceCount(__dpctl_keep const DPCTLSyclContextRef CRef); * * @param CRef DPCTLSyclContexRef object to query. * @return A DPCTLDeviceVectorRef with devices associated with given CRef. + * @ingroup ContextInterface */ DPCTL_API __dpctl_give DPCTLDeviceVectorRef @@ -125,6 +135,7 @@ DPCTLContext_GetDevices(__dpctl_keep const DPCTLSyclContextRef CRef); * * @param CtxRef An opaque pointer to a sycl::context. * @return True if the SYCL context is a host context, else False. + * @ingroup ContextInterface */ DPCTL_API bool DPCTLContext_IsHost(__dpctl_keep const DPCTLSyclContextRef CtxRef); @@ -135,6 +146,7 @@ bool DPCTLContext_IsHost(__dpctl_keep const DPCTLSyclContextRef CtxRef); * @param CtxRef An opaque pointer to a sycl::context. * @return The sycl backend for the DPCTLSyclContextRef returned as * a DPCTLSyclBackendType enum type. + * @ingroup ContextInterface */ DPCTL_API DPCTLSyclBackendType @@ -144,6 +156,7 @@ DPCTLContext_GetBackend(__dpctl_keep const DPCTLSyclContextRef CtxRef); * @brief Delete the pointer after casting it to sycl::context * * @param CtxRef The DPCTLSyclContextRef pointer to be deleted. + * @ingroup ContextInterface */ DPCTL_API void DPCTLContext_Delete(__dpctl_take DPCTLSyclContextRef CtxRef); diff --git a/dpctl-capi/include/dpctl_sycl_device_interface.h b/dpctl-capi/include/dpctl_sycl_device_interface.h index 09d0f1b7ef..be69f34447 100644 --- a/dpctl-capi/include/dpctl_sycl_device_interface.h +++ b/dpctl-capi/include/dpctl_sycl_device_interface.h @@ -37,12 +37,17 @@ DPCTL_C_EXTERN_C_BEGIN +/** + * @defgroup DeviceInterface Device class C wrapper + */ + /*! * @brief Returns a copy of the DPCTLSyclDeviceRef object. * * @param DRef DPCTLSyclDeviceRef object to be copied. * @return A new DPCTLSyclDeviceRef created by copying the passed in * DPCTLSyclDeviceRef object. + * @ingroup DeviceInterface */ DPCTL_API __dpctl_give DPCTLSyclDeviceRef @@ -53,6 +58,7 @@ DPCTLDevice_Copy(__dpctl_keep const DPCTLSyclDeviceRef DRef); * instance as a host device. * * @return An opaque pointer to the host SYCL device. + * @ingroup DeviceInterface */ DPCTL_API __dpctl_give DPCTLSyclDeviceRef DPCTLDevice_Create(); @@ -65,6 +71,7 @@ __dpctl_give DPCTLSyclDeviceRef DPCTLDevice_Create(); * @return Returns an opaque pointer to a SYCL device created using the * device_selector, if the requested device could not be created a * nullptr is returned. + * @ingroup DeviceInterface */ DPCTL_API __dpctl_give DPCTLSyclDeviceRef DPCTLDevice_CreateFromSelector( @@ -74,6 +81,7 @@ __dpctl_give DPCTLSyclDeviceRef DPCTLDevice_CreateFromSelector( * @brief Deletes a DPCTLSyclDeviceRef pointer after casting to to sycl::device. * * @param DRef The DPCTLSyclDeviceRef pointer to be freed. + * @ingroup DeviceInterface */ DPCTL_API void DPCTLDevice_Delete(__dpctl_take DPCTLSyclDeviceRef DRef); @@ -84,6 +92,7 @@ void DPCTLDevice_Delete(__dpctl_take DPCTLSyclDeviceRef DRef); * * @param DRef Opaque pointer to a sycl::device * @return True if the device type is an accelerator, else False. + * @ingroup DeviceInterface */ DPCTL_API bool DPCTLDevice_IsAccelerator(__dpctl_keep const DPCTLSyclDeviceRef DRef); @@ -94,6 +103,7 @@ bool DPCTLDevice_IsAccelerator(__dpctl_keep const DPCTLSyclDeviceRef DRef); * * @param DRef Opaque pointer to a sycl::device * @return True if the device type is a cpu, else False. + * @ingroup DeviceInterface */ DPCTL_API bool DPCTLDevice_IsCPU(__dpctl_keep const DPCTLSyclDeviceRef DRef); @@ -104,6 +114,7 @@ bool DPCTLDevice_IsCPU(__dpctl_keep const DPCTLSyclDeviceRef DRef); * * @param DRef Opaque pointer to a sycl::device * @return True if the device type is a gpu, else False. + * @ingroup DeviceInterface */ DPCTL_API bool DPCTLDevice_IsGPU(__dpctl_keep const DPCTLSyclDeviceRef DRef); @@ -113,6 +124,7 @@ bool DPCTLDevice_IsGPU(__dpctl_keep const DPCTLSyclDeviceRef DRef); * * @param DRef Opaque pointer to a sycl::device * @return True if the device is a host device, else False. + * @ingroup DeviceInterface */ DPCTL_API bool DPCTLDevice_IsHost(__dpctl_keep const DPCTLSyclDeviceRef DRef); @@ -123,6 +135,7 @@ bool DPCTLDevice_IsHost(__dpctl_keep const DPCTLSyclDeviceRef DRef); * @param DRef Opaque pointer to a sycl::device * @return A DPCTLSyclBackendType enum value representing the sycl::backend * for the device. + * @ingroup DeviceInterface */ DPCTL_API DPCTLSyclBackendType @@ -134,6 +147,7 @@ DPCTLDevice_GetBackend(__dpctl_keep const DPCTLSyclDeviceRef DRef); * * @param DRef Opaque pointer to a sycl::device * @return The DPCTLSyclDeviceType value corresponding to the device. + * @ingroup DeviceInterface */ DPCTL_API DPCTLSyclDeviceType @@ -145,6 +159,7 @@ DPCTLDevice_GetDeviceType(__dpctl_keep const DPCTLSyclDeviceRef DRef); * @param DRef Opaque pointer to a sycl::device * @return A C string in the form major_number.minor.number that corresponds * to the OpenCL driver version if this is a OpenCL device. + * @ingroup DeviceInterface */ DPCTL_API __dpctl_give const char * @@ -155,6 +170,7 @@ DPCTLDevice_GetDriverInfo(__dpctl_keep const DPCTLSyclDeviceRef DRef); * * @param DRef Opaque pointer to a sycl::device * @return Returns the valid result if device exists else returns 0. + * @ingroup DeviceInterface */ DPCTL_API uint32_t @@ -165,6 +181,7 @@ DPCTLDevice_GetMaxComputeUnits(__dpctl_keep const DPCTLSyclDeviceRef DRef); * * @param DRef Opaque pointer to a sycl::device * @return Returns the valid result if device exists else returns 0. + * @ingroup DeviceInterface */ DPCTL_API uint32_t @@ -175,6 +192,7 @@ DPCTLDevice_GetMaxWorkItemDims(__dpctl_keep const DPCTLSyclDeviceRef DRef); * * @param DRef Opaque pointer to a sycl::device * @return Returns the valid result if device exists else returns NULL. + * @ingroup DeviceInterface */ DPCTL_API __dpctl_keep size_t * @@ -185,6 +203,7 @@ DPCTLDevice_GetMaxWorkItemSizes(__dpctl_keep const DPCTLSyclDeviceRef DRef); * * @param DRef Opaque pointer to a sycl::device * @return Returns the valid result if device exists else returns 0. + * @ingroup DeviceInterface */ DPCTL_API size_t @@ -195,6 +214,7 @@ DPCTLDevice_GetMaxWorkGroupSize(__dpctl_keep const DPCTLSyclDeviceRef DRef); * * @param DRef Opaque pointer to a sycl::device * @return Returns the valid result if device exists else returns 0. + * @ingroup DeviceInterface */ DPCTL_API uint32_t @@ -206,6 +226,7 @@ DPCTLDevice_GetMaxNumSubGroups(__dpctl_keep const DPCTLSyclDeviceRef DRef); * * @param DRef Opaque pointer to a sycl::device * @return An opaque pointer to the sycl::platform for the device. + * @ingroup DeviceInterface */ DPCTL_API __dpctl_give DPCTLSyclPlatformRef @@ -216,6 +237,7 @@ DPCTLDevice_GetPlatform(__dpctl_keep const DPCTLSyclDeviceRef DRef); * * @param DRef Opaque pointer to a sycl::device * @return A C string containing the OpenCL device name. + * @ingroup DeviceInterface */ DPCTL_API __dpctl_give const char * @@ -226,6 +248,7 @@ DPCTLDevice_GetName(__dpctl_keep const DPCTLSyclDeviceRef DRef); * * @param DRef Opaque pointer to a sycl::device * @return A C string containing the OpenCL device vendor name. + * @ingroup DeviceInterface */ DPCTL_API __dpctl_give const char * @@ -238,6 +261,7 @@ DPCTLDevice_GetVendorName(__dpctl_keep const DPCTLSyclDeviceRef DRef); * @param DRef Opaque pointer to a sycl::device * @return Boolean indicating if the device shares a unified memory subsystem * with the host. + * @ingroup DeviceInterface */ DPCTL_API bool DPCTLDevice_IsHostUnifiedMemory( @@ -250,10 +274,11 @@ bool DPCTLDevice_IsHostUnifiedMemory( * @param DRef1 First opaque pointer to a sycl device. * @param DRef2 Second opaque pointer to a sycl device. * @return True if the underlying sycl::device are same, false otherwise. + * @ingroup DeviceInterface */ DPCTL_API -bool DPCTLDevice_AreEq(__dpctl_keep const DPCTLSyclDeviceRef DevRef1, - __dpctl_keep const DPCTLSyclDeviceRef DevRef2); +bool DPCTLDevice_AreEq(__dpctl_keep const DPCTLSyclDeviceRef DRef1, + __dpctl_keep const DPCTLSyclDeviceRef DRef2); /*! * @brief Checks if device has aspect. @@ -261,6 +286,7 @@ bool DPCTLDevice_AreEq(__dpctl_keep const DPCTLSyclDeviceRef DevRef1, * @param DRef Opaque pointer to a sycl::device * @param AT DPCTLSyclAspectType of device::aspect. * @return True if sycl::device has device::aspect, else false. + * @ingroup DeviceInterface */ DPCTL_API bool DPCTLDevice_HasAspect(__dpctl_keep const DPCTLSyclDeviceRef DRef, @@ -369,6 +395,7 @@ DPCTLDevice_GetImage3dMaxDepth(__dpctl_keep const DPCTLSyclDeviceRef DRef); * @param count Count compute units that need to contains in * subdevices * @return A #DPCTLDeviceVectorRef containing #DPCTLSyclDeviceRef objects + * @ingroup DeviceInterface */ DPCTL_API __dpctl_give DPCTLDeviceVectorRef @@ -386,6 +413,7 @@ DPCTLDevice_CreateSubDevicesEqually(__dpctl_keep const DPCTLSyclDeviceRef DRef, * that need to contains in subdevices * @param ncounts Number of counts * @return A #DPCTLDeviceVectorRef containing #DPCTLSyclDeviceRef objects + * @ingroup DeviceInterface */ DPCTL_API __dpctl_give DPCTLDeviceVectorRef @@ -394,14 +422,16 @@ DPCTLDevice_CreateSubDevicesByCounts(__dpctl_keep const DPCTLSyclDeviceRef DRef, size_t ncounts); /*! - * @brief Returns a vector of sub devices + * @brief Returns a vector of sub-devices * partitioned from this SYCL device by affinity domain based on the domain * parameter. * - * @param DRef Opaque pointer to a sycl::device - * @param DPCTLPartitionAffinityDomainType DPCTLPartitionAffinityDomainType - * of sycl::info::partition_affinity_domain + * @param DRef Opaque pointer to a ``sycl::device`` + * @param DPCTLPartitionAffinityDomainType PartitionAffinityDomainTy + * of ``sycl::info::partition_affinity_domain`` + * * @return A #DPCTLDeviceVectorRef containing #DPCTLSyclDeviceRef objects + * @ingroup DeviceInterface */ DPCTL_API __dpctl_give DPCTLDeviceVectorRef DPCTLDevice_CreateSubDevicesByAffinity( @@ -414,9 +444,10 @@ DPCTL_C_EXTERN_C_END * @brief Wrapper over * device.get_info. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return Returns true if the device supports independent forward progress of * sub-groups with respect to other sub-groups in the same work-group. + * @ingroup DeviceInterface */ DPCTL_API bool DPCTLDevice_GetSubGroupIndependentForwardProgress( @@ -429,6 +460,7 @@ bool DPCTLDevice_GetSubGroupIndependentForwardProgress( * @param DRef Opaque pointer to a sycl::device * @return Returns the preferred native vector width size for built-in scalar * types that can be put into vectors. + * @ingroup DeviceInterface */ DPCTL_API uint32_t DPCTLDevice_GetPreferredVectorWidthChar( @@ -441,6 +473,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthChar( * @param DRef Opaque pointer to a sycl::device * @return Returns the preferred native vector width size for built-in scalar * types that can be put into vectors. + * @ingroup DeviceInterface */ DPCTL_API uint32_t DPCTLDevice_GetPreferredVectorWidthShort( @@ -453,6 +486,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthShort( * @param DRef Opaque pointer to a sycl::device * @return Returns the preferred native vector width size for built-in scalar * types that can be put into vectors. + * @ingroup DeviceInterface */ DPCTL_API uint32_t DPCTLDevice_GetPreferredVectorWidthInt( @@ -465,6 +499,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthInt( * @param DRef Opaque pointer to a sycl::device * @return Returns the preferred native vector width size for built-in scalar * types that can be put into vectors. + * @ingroup DeviceInterface */ DPCTL_API uint32_t DPCTLDevice_GetPreferredVectorWidthLong( @@ -474,9 +509,10 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthLong( * @brief Wrapper over * device.get_info. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer * @return Returns the preferred native vector width size for built-in scalar - * types that can be put into vectors. + * type. + * @ingroup DeviceInterface */ DPCTL_API uint32_t DPCTLDevice_GetPreferredVectorWidthFloat( @@ -489,6 +525,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthFloat( * @param DRef Opaque pointer to a sycl::device * @return Returns the preferred native vector width size for built-in scalar * types that can be put into vectors. + * @ingroup DeviceInterface */ DPCTL_API uint32_t DPCTLDevice_GetPreferredVectorWidthDouble( @@ -501,6 +538,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthDouble( * @param DRef Opaque pointer to a sycl::device * @return Returns the preferred native vector width size for built-in scalar * types that can be put into vectors. + * @ingroup DeviceInterface */ DPCTL_API uint32_t DPCTLDevice_GetPreferredVectorWidthHalf( diff --git a/dpctl-capi/include/dpctl_sycl_device_manager.h b/dpctl-capi/include/dpctl_sycl_device_manager.h index 37c02e241b..467ab9cff6 100644 --- a/dpctl-capi/include/dpctl_sycl_device_manager.h +++ b/dpctl-capi/include/dpctl_sycl_device_manager.h @@ -35,8 +35,10 @@ DPCTL_C_EXTERN_C_BEGIN -/** - * @defgroup DeviceManager Device management helper functions +/*! \addtogroup DeviceManager Device class helper functions + * Helper functions for sycl::device objects that do not directly map to any + * sycl::device member function. + * @{ */ // Declares a set of types abd functions to deal with vectors of @@ -69,7 +71,6 @@ DPCTL_DECLARE_VECTOR(Device) * enum values. * @return A #DPCTLDeviceVectorRef containing #DPCTLSyclDeviceRef objects * that match the device identifier bit flags. - * @ingroup DeviceManager */ DPCTL_API __dpctl_give DPCTLDeviceVectorRef @@ -101,7 +102,6 @@ DPCTLDeviceMgr_GetCachedContext(__dpctl_keep const DPCTLSyclDeviceRef DRef); * the enum values or a bitwise OR-ed combination. * @return The number of available devices satisfying the condition specified * by the device_identifier bit flag. - * @ingroup DeviceManager */ DPCTL_API size_t DPCTLDeviceMgr_GetNumDevices(int device_identifier); @@ -111,7 +111,6 @@ size_t DPCTLDeviceMgr_GetNumDevices(int device_identifier); * currently supported by dpctl. * * @param DRef A #DPCTLSyclDeviceRef opaque pointer. - * @ingroup DeviceManager */ DPCTL_API void DPCTLDeviceMgr_PrintDeviceInfo(__dpctl_keep const DPCTLSyclDeviceRef DRef); @@ -127,4 +126,6 @@ DPCTL_API int64_t DPCTLDeviceMgr_GetRelativeId(__dpctl_keep const DPCTLSyclDeviceRef DRef); +/*! @} */ + DPCTL_C_EXTERN_C_END diff --git a/dpctl-capi/include/dpctl_sycl_device_selector_interface.h b/dpctl-capi/include/dpctl_sycl_device_selector_interface.h index d9217027fd..41ef4590e2 100644 --- a/dpctl-capi/include/dpctl_sycl_device_selector_interface.h +++ b/dpctl-capi/include/dpctl_sycl_device_selector_interface.h @@ -34,7 +34,7 @@ DPCTL_C_EXTERN_C_BEGIN /** - * \defgroup DeviceSelectors C API for SYCL Device Selectors + * @defgroup DeviceSelectors Device selection */ /*! @@ -50,6 +50,7 @@ __dpctl_give DPCTLSyclDeviceSelectorRef DPCTLAcceleratorSelector_Create(); * @brief Returns an opaque wrapper for sycl::default_selector object. * * @return An opaque pointer to a sycl::default_selector object. + * @ingroup DeviceSelectors */ DPCTL_API __dpctl_give DPCTLSyclDeviceSelectorRef DPCTLDefaultSelector_Create(); diff --git a/dpctl-capi/include/dpctl_sycl_enum_types.h b/dpctl-capi/include/dpctl_sycl_enum_types.h index 9b20d3432c..5148f23a56 100644 --- a/dpctl-capi/include/dpctl_sycl_enum_types.h +++ b/dpctl-capi/include/dpctl_sycl_enum_types.h @@ -123,7 +123,7 @@ enum DPCTLSyclAspectType }; /*! - * @brief DPCTL analogue of sycl::info::partition_affinity_domain enum + * @brief DPCTL analogue of ``sycl::info::partition_affinity_domain`` enum. * */ enum DPCTLPartitionAffinityDomainType diff --git a/dpctl-capi/include/dpctl_sycl_event_interface.h b/dpctl-capi/include/dpctl_sycl_event_interface.h index b5e540a9b5..92b3d27c5e 100644 --- a/dpctl-capi/include/dpctl_sycl_event_interface.h +++ b/dpctl-capi/include/dpctl_sycl_event_interface.h @@ -33,11 +33,16 @@ DPCTL_C_EXTERN_C_BEGIN +/** + * @defgroup EventInterface Event class C wrapper + */ + /*! * @brief C-API wrapper for sycl::event.wait. * * @param ERef An opaque DPCTLSyclEventRef pointer on which to * wait. + * @ingroup EventInterface */ DPCTL_API void DPCTLEvent_Wait(__dpctl_keep DPCTLSyclEventRef ERef); @@ -47,6 +52,7 @@ void DPCTLEvent_Wait(__dpctl_keep DPCTLSyclEventRef ERef); * * @param ERef An opaque DPCTLSyclEventRef pointer that would be * freed. + * @ingroup EventInterface */ DPCTL_API void DPCTLEvent_Delete(__dpctl_take DPCTLSyclEventRef ERef); diff --git a/dpctl-capi/include/dpctl_sycl_kernel_interface.h b/dpctl-capi/include/dpctl_sycl_kernel_interface.h index 105c4a5acc..582b19b6ef 100644 --- a/dpctl-capi/include/dpctl_sycl_kernel_interface.h +++ b/dpctl-capi/include/dpctl_sycl_kernel_interface.h @@ -34,6 +34,10 @@ DPCTL_C_EXTERN_C_BEGIN +/** + * @defgroup KernelInterface Kernel class C wrapper + */ + /*! * @brief Returns a C string for the kernel name. * @@ -41,6 +45,7 @@ DPCTL_C_EXTERN_C_BEGIN * interoperability kernel. * @return If a kernel name exists then returns it as a C string, else * returns a nullptr. + * @ingroup KernelInterface */ DPCTL_API __dpctl_give const char * @@ -53,6 +58,7 @@ DPCTLKernel_GetFunctionName(__dpctl_keep const DPCTLSyclKernelRef KRef); * interoperability kernel. * @return Returns the number of arguments for the OpenCL interoperability * kernel. + * @ingroup KernelInterface */ DPCTL_API size_t DPCTLKernel_GetNumArgs(__dpctl_keep const DPCTLSyclKernelRef KRef); @@ -62,6 +68,7 @@ size_t DPCTLKernel_GetNumArgs(__dpctl_keep const DPCTLSyclKernelRef KRef); * * @param KRef DPCTLSyclKernelRef pointer to an OpenCL * interoperability kernel. + * @ingroup KernelInterface */ DPCTL_API void DPCTLKernel_Delete(__dpctl_take DPCTLSyclKernelRef KRef); diff --git a/dpctl-capi/include/dpctl_sycl_platform_interface.h b/dpctl-capi/include/dpctl_sycl_platform_interface.h index d67273cf41..5e9cd02deb 100644 --- a/dpctl-capi/include/dpctl_sycl_platform_interface.h +++ b/dpctl-capi/include/dpctl_sycl_platform_interface.h @@ -35,12 +35,17 @@ DPCTL_C_EXTERN_C_BEGIN +/** + * @defgroup PlatformInterface Platform class C wrapper + */ + /*! * @brief Returns a copy of the DPCTLSyclPlatformRef object. * - * @param DRef DPCTLSyclPlatformRef object to be copied. + * @param PRef DPCTLSyclPlatformRef object to be copied. * @return A new DPCTLSyclPlatformRef created by copying the passed in * DPCTLSyclPlatformRef object. + * @ingroup PlatformInterface */ DPCTL_API __dpctl_give DPCTLSyclPlatformRef @@ -51,6 +56,7 @@ DPCTLPlatform_Copy(__dpctl_keep const DPCTLSyclPlatformRef PRef); * using SYCL's default_selector. * * @return A new DPCTLSyclPlatformRef pointer wrapping a SYCL platform object. + * @ingroup PlatformInterface */ DPCTL_API __dpctl_give DPCTLSyclPlatformRef DPCTLPlatform_Create(); @@ -61,6 +67,7 @@ __dpctl_give DPCTLSyclPlatformRef DPCTLPlatform_Create(); * * @param DSRef An opaque pointer to a SYCL device_selector object. * @return A new DPCTLSyclPlatformRef pointer wrapping a SYCL platform object. + * @ingroup PlatformInterface */ DPCTL_API __dpctl_give DPCTLSyclPlatformRef DPCTLPlatform_CreateFromSelector( @@ -70,6 +77,7 @@ __dpctl_give DPCTLSyclPlatformRef DPCTLPlatform_CreateFromSelector( * @brief Deletes the DPCTLSyclProgramRef pointer. * * @param PRef An opaque pointer to a sycl::platform. + * @ingroup PlatformInterface */ DPCTL_API void DPCTLPlatform_Delete(__dpctl_take DPCTLSyclPlatformRef PRef); @@ -81,6 +89,7 @@ void DPCTLPlatform_Delete(__dpctl_take DPCTLSyclPlatformRef PRef); * @param PRef Opaque pointer to a sycl::platform * @return A DPCTLSyclBackendType enum value identifying the SYCL backend * associated with the platform. + * @ingroup PlatformInterface */ DPCTL_API DPCTLSyclBackendType @@ -91,6 +100,7 @@ DPCTLPlatform_GetBackend(__dpctl_keep const DPCTLSyclPlatformRef PRef); * * @param PRef Opaque pointer to a sycl::platform * @return A C string containing the name of the sycl::platform. + * @ingroup PlatformInterface */ DPCTL_API __dpctl_give const char * @@ -102,6 +112,7 @@ DPCTLPlatform_GetName(__dpctl_keep const DPCTLSyclPlatformRef PRef); * @param PRef Opaque pointer to a sycl::platform * @return A C string containing the name of the vendor provifing the * platform. + * @ingroup PlatformInterface */ DPCTL_API __dpctl_give const char * @@ -114,6 +125,7 @@ DPCTLPlatform_GetVendor(__dpctl_keep const DPCTLSyclPlatformRef PRef); * @param PRef Opaque pointer to a sycl::platform * @return A C string containing the software driver version of the device * associated with the platform. + * @ingroup PlatformInterface */ DPCTL_API __dpctl_give const char * @@ -125,6 +137,7 @@ DPCTLPlatform_GetVersion(__dpctl_keep const DPCTLSyclPlatformRef PRef); * * @return A #DPCTLPlatformVectorRef containing #DPCTLSyclPlatformRef * objects. + * @ingroup PlatformInterface */ DPCTL_API __dpctl_give DPCTLPlatformVectorRef DPCTLPlatform_GetPlatforms(); diff --git a/dpctl-capi/include/dpctl_sycl_platform_manager.h b/dpctl-capi/include/dpctl_sycl_platform_manager.h index 1dc079973c..4881ace6b9 100644 --- a/dpctl-capi/include/dpctl_sycl_platform_manager.h +++ b/dpctl-capi/include/dpctl_sycl_platform_manager.h @@ -33,6 +33,12 @@ DPCTL_C_EXTERN_C_BEGIN +/*! \addtogroup PlatformManager Platform class helper functions + * Helper functions for ``sycl::platform`` objects that do not directly map to + * any ``sycl::platform`` member function. + * @{ + */ + // Declares a set of types abd functions to deal with vectors of // DPCTLSyclPlatformRef. Refer dpctl_vector_macros.h DPCTL_DECLARE_VECTOR(Platform) @@ -44,4 +50,6 @@ DPCTL_DECLARE_VECTOR(Platform) DPCTL_API void DPCTLPlatformMgr_PrintInfo(__dpctl_keep const DPCTLSyclPlatformRef PRef); +/*! @} */ + DPCTL_C_EXTERN_C_END diff --git a/dpctl-capi/include/dpctl_sycl_program_interface.h b/dpctl-capi/include/dpctl_sycl_program_interface.h index 349c7204f2..4667631a98 100644 --- a/dpctl-capi/include/dpctl_sycl_program_interface.h +++ b/dpctl-capi/include/dpctl_sycl_program_interface.h @@ -34,6 +34,10 @@ DPCTL_C_EXTERN_C_BEGIN +/** + * @defgroup ProgramInterface Program class C wrapper + */ + /*! * @brief Create a Sycl program from an OpenCL SPIR-V binary file. * @@ -53,6 +57,7 @@ DPCTL_C_EXTERN_C_BEGIN * SPIR-V binary. * @return A new SyclProgramRef pointer if the program creation succeeded, * else returns NULL. + * @ingroup ProgramInterface */ DPCTL_API __dpctl_give DPCTLSyclProgramRef @@ -69,6 +74,7 @@ DPCTLProgram_CreateFromSpirv(__dpctl_keep const DPCTLSyclContextRef Ctx, * @param CompileOpts Extra compiler flags (refer Sycl spec.) * @return A new SyclProgramRef pointer if the program creation succeeded, * else returns NULL. + * @ingroup ProgramInterface */ DPCTL_API __dpctl_give DPCTLSyclProgramRef @@ -83,6 +89,7 @@ DPCTLProgram_CreateFromOCLSource(__dpctl_keep const DPCTLSyclContextRef Ctx, * @param PRef Opaque pointer to a sycl::program * @param KernelName Name of kernel * @return A SyclKernel reference if the kernel exists, else NULL + * @ingroup ProgramInterface */ DPCTL_API __dpctl_give DPCTLSyclKernelRef @@ -96,6 +103,7 @@ DPCTLProgram_GetKernel(__dpctl_keep DPCTLSyclProgramRef PRef, * @param PRef Opaque pointer to a sycl::program * @param KernelName Name of kernel * @return True if the kernel exists, else False + * @ingroup ProgramInterface */ DPCTL_API bool DPCTLProgram_HasKernel(__dpctl_keep DPCTLSyclProgramRef PRef, @@ -105,6 +113,7 @@ bool DPCTLProgram_HasKernel(__dpctl_keep DPCTLSyclProgramRef PRef, * @brief Frees the DPCTLSyclProgramRef pointer. * * @param PRef Opaque pointer to a sycl::program + * @ingroup ProgramInterface */ DPCTL_API void DPCTLProgram_Delete(__dpctl_take DPCTLSyclProgramRef PRef); diff --git a/dpctl-capi/include/dpctl_sycl_queue_interface.h b/dpctl-capi/include/dpctl_sycl_queue_interface.h index 36e6f42137..8871e58dcc 100644 --- a/dpctl-capi/include/dpctl_sycl_queue_interface.h +++ b/dpctl-capi/include/dpctl_sycl_queue_interface.h @@ -38,7 +38,7 @@ DPCTL_C_EXTERN_C_BEGIN /** - * @defgroup QueueInterface sycl::queue class wrapper functions. + * @defgroup QueueInterface Queue class C wrapper */ /*! @@ -66,28 +66,36 @@ DPCTLQueue_Create(__dpctl_keep const DPCTLSyclContextRef CRef, int properties); /*! - * @brief Constructs a sycl::queue object of the specified SYCL device. + * @brief Constructs a ``sycl::queue`` object of the specified SYCL device. * - * Constructs a new SYCL queue for the specified SYCL device. The behaviour of - * this function differs from the SYCL `queue(const device &syclDevice, const - * async_handler &asyncHandler, const property_list &propList = {})` constructor - * of the queue class. Unlike the SYCL queue class constructor, we try not to - * create a new SYCL context for the device and instead look to reuse a - * previously cached SYCL context for the device (refer - * dpctl_sycl_device_manager.cpp). DPCTL caches contexts only for root devices - * and for all custom devices the function begaves the same way as the SYCL - * constructor. + * Constructs a new SYCL queue for the specified SYCL device. The + * behaviour of this function differs from the following queue constructor: * - * @param dRef An opaque pointer to a sycl::device. + * @code + * queue( + * const device &syclDevice, + * const async_handler &asyncHandler, + * const property_list &propList = {} + * ) + * @endcode + * + * Unlike the SYCL queue constructor, we try not to create a new SYCL + * context for the device and instead look to reuse a previously cached + * SYCL context for the device (refer dpctl_sycl_device_manager.cpp). + * DPCTL caches contexts only for root devices and for all custom devices the + * function begaves the same way as the SYCL constructor. + * + * @param dRef An opaque pointer to a ``sycl::device``. * @param error_handler A callback function that will be invoked by the * async_handler used during queue creation. Can be * NULL if no async_handler is needed. * @param properties A combination of bit flags using the values defined * in the DPCTLQueuePropertyType enum. The bit flags - * are used to create a sycl::property_list that is + * are used to create a ``sycl::property_list`` that is * passed to the SYCL queue constructor. - * @return An opaque DPCTLSyclQueueRef pointer containing the new sycl::queue - * object. A nullptr is returned if the queue could not be created. + * @return An opaque DPCTLSyclQueueRef pointer containing the new + * ``sycl::queue`` object. A nullptr is returned if the queue could not be + * created. * @ingroup QueueInterface */ DPCTL_API @@ -108,9 +116,10 @@ void DPCTLQueue_Delete(__dpctl_take DPCTLSyclQueueRef QRef); /*! * @brief Returns a copy of the DPCTLSyclQueueRef object. * - * @param DRef DPCTLSyclQueueRef object to be copied. + * @param QRef DPCTLSyclQueueRef object to be copied. * @return A new DPCTLSyclQueueRef created by copying the passed in * DPCTLSyclQueueRef object. + * @ingroup QueueInterface */ DPCTL_API __dpctl_give DPCTLSyclQueueRef diff --git a/dpctl-capi/include/dpctl_sycl_queue_manager.h b/dpctl-capi/include/dpctl_sycl_queue_manager.h index bdb3586c1f..03915433b2 100644 --- a/dpctl-capi/include/dpctl_sycl_queue_manager.h +++ b/dpctl-capi/include/dpctl_sycl_queue_manager.h @@ -35,7 +35,7 @@ DPCTL_C_EXTERN_C_BEGIN /** - * @defgroup QueueManager Queue management helper functions + * @defgroup QueueManager Queue class helper functions */ /*! @@ -129,6 +129,7 @@ void DPCTLQueueMgr_PopQueue(); * objects. * * @return The current size of the queue manager's stack of queues. + * @ingroup QueueManager */ DPCTL_API size_t DPCTLQueueMgr_GetQueueStackSize(); diff --git a/dpctl-capi/include/dpctl_sycl_types.h b/dpctl-capi/include/dpctl_sycl_types.h index 9060ea21c5..12fadb901c 100644 --- a/dpctl-capi/include/dpctl_sycl_types.h +++ b/dpctl-capi/include/dpctl_sycl_types.h @@ -30,58 +30,56 @@ DPCTL_C_EXTERN_C_BEGIN /*! - * @brief Opaque pointer to a sycl::context + * @brief Opaque pointer to a ``sycl::context`` * */ typedef struct DPCTLOpaqueSyclContext *DPCTLSyclContextRef; /*! - * @brief Opaque pointer to a sycl::device + * @brief Opaque pointer to a ``sycl::device`` * */ typedef struct DPCTLOpaqueSyclDevice *DPCTLSyclDeviceRef; /*! - * @brief Opaque pointer to a sycl::device_selector + * @brief Opaque pointer to a ``sycl::device_selector`` * */ typedef struct DPCTLOpaqueSyclDeviceSelector *DPCTLSyclDeviceSelectorRef; /*! - * @brief Opaque pointer to a sycl::event + * @brief Opaque pointer to a ``sycl::event`` * */ typedef struct DPCTLOpaqueSyclEvent *DPCTLSyclEventRef; /*! - * @brief Opaque pointer to a sycl::kernel + * @brief Opaque pointer to a ``sycl::kernel`` * */ typedef struct DPCTLOpaqueSyclKernel *DPCTLSyclKernelRef; /*! - * @brief Opaque pointer to a sycl::platform + * @brief Opaque pointer to a ``sycl::platform`` * */ typedef struct DPCTLOpaqueSyclPlatform *DPCTLSyclPlatformRef; /*! - * @brief Opaque pointer to a sycl::program + * @brief Opaque pointer to a ``sycl::program`` * */ typedef struct DPCTLOpaqueSyclProgram *DPCTLSyclProgramRef; /*! - * @brief Opaque pointer to a sycl::queue + * @brief Opaque pointer to a ``sycl::queue`` * - * @see sycl::queue */ typedef struct DPCTLOpaqueSyclQueue *DPCTLSyclQueueRef; /*! - * @brief Used to pass a sycl::usm memory opaquely through DPCTL interfaces. + * @brief Used to pass a ``sycl::usm`` memory opaquely through DPCTL interfaces. * - * @see sycl::usm */ typedef struct DPCTLOpaqueSyclUSM *DPCTLSyclUSMRef; diff --git a/dpctl-capi/include/dpctl_sycl_usm_interface.h b/dpctl-capi/include/dpctl_sycl_usm_interface.h index c5a0efe120..318559fb6e 100644 --- a/dpctl-capi/include/dpctl_sycl_usm_interface.h +++ b/dpctl-capi/include/dpctl_sycl_usm_interface.h @@ -33,6 +33,10 @@ DPCTL_C_EXTERN_C_BEGIN +/** + * @defgroup USMInterface USM Interface + */ + /*! * @brief Create USM shared memory. * @@ -40,6 +44,7 @@ DPCTL_C_EXTERN_C_BEGIN * @param QRef Sycl queue reference to use in allocation * * @return The pointer to USM shared memory. On failure, returns nullptr. + * @ingroup USMInterface */ DPCTL_API __dpctl_give DPCTLSyclUSMRef @@ -54,6 +59,7 @@ DPCTLmalloc_shared(size_t size, __dpctl_keep const DPCTLSyclQueueRef QRef); * * @return The pointer to USM shared memory with the requested alignment. * On failure, returns nullptr. + * @ingroup USMInterface */ DPCTL_API __dpctl_give DPCTLSyclUSMRef @@ -68,6 +74,7 @@ DPCTLaligned_alloc_shared(size_t alignment, * @param QRef Sycl queue reference to use in allocation * * @return The pointer to USM host memory. On failure, returns nullptr. + * @ingroup USMInterface */ DPCTL_API __dpctl_give DPCTLSyclUSMRef @@ -82,6 +89,7 @@ DPCTLmalloc_host(size_t size, __dpctl_keep const DPCTLSyclQueueRef QRef); * * @return The pointer to USM host memory with the requested alignment. * On failure, returns nullptr. + * @ingroup USMInterface */ DPCTL_API __dpctl_give DPCTLSyclUSMRef @@ -96,6 +104,7 @@ DPCTLaligned_alloc_host(size_t alignment, * @param QRef Sycl queue reference to use in allocation * * @return The pointer to USM device memory. On failure, returns nullptr. + * @ingroup USMInterface */ DPCTL_API __dpctl_give DPCTLSyclUSMRef @@ -110,6 +119,7 @@ DPCTLmalloc_device(size_t size, __dpctl_keep const DPCTLSyclQueueRef QRef); * * @return The pointer to USM device memory with requested alignment. * On failure, returns nullptr. + * @ingroup USMInterface */ DPCTL_API __dpctl_give DPCTLSyclUSMRef @@ -125,6 +135,7 @@ DPCTLaligned_alloc_device(size_t alignment, * * USM pointer must have been allocated using the same context as the one * used to construct the queue. + * @ingroup USMInterface */ DPCTL_API void DPCTLfree_with_queue(__dpctl_take DPCTLSyclUSMRef MRef, @@ -132,7 +143,9 @@ void DPCTLfree_with_queue(__dpctl_take DPCTLSyclUSMRef MRef, /*! * @brief Free USM memory. - * + * @param MRef USM pointer to free + * @param CRef Sycl context reference to use. + * @ingroup USMInterface */ DPCTL_API void DPCTLfree_with_context(__dpctl_take DPCTLSyclUSMRef MRef, @@ -145,6 +158,7 @@ void DPCTLfree_with_context(__dpctl_take DPCTLSyclUSMRef MRef, * @param CRef Sycl context reference associated with the pointer * * @return "host", "device", "shared" or "unknown" + * @ingroup USMInterface */ DPCTL_API const char * @@ -158,6 +172,7 @@ DPCTLUSM_GetPointerType(__dpctl_keep const DPCTLSyclUSMRef MRef, * @param CRef Sycl context reference associated with the pointer * * @return A DPCTLSyclDeviceRef pointer to the sycl device. + * @ingroup USMInterface */ DPCTL_API DPCTLSyclDeviceRef diff --git a/dpctl-capi/include/dpctl_vector.h b/dpctl-capi/include/dpctl_vector.h index 4ed7ecef31..ec50fa437d 100644 --- a/dpctl-capi/include/dpctl_vector.h +++ b/dpctl-capi/include/dpctl_vector.h @@ -33,29 +33,63 @@ DPCTL_C_EXTERN_C_BEGIN +/*! + * @brief Declare an opaque pointer type for a std::vector of opaque pointers + * wrapping SYCL data types. + */ #define DPCTL_DECLARE_VECTOR_TYPE(EL) \ typedef struct DPCTL##EL##Vector *DPCTL##EL##VectorRef; #define DPCTL_DECLARE_VECTOR_FN(EL) \ + /*! \ + @brief Create an opaque pointer to a std::vector of opaque pointers \ + wrapping the SYCL data type. \ + @return Returns a new opaque pointer to a vector. \ + */ \ DPCTL_API \ __dpctl_give DPCTL##EL##VectorRef DPCTL##EL##Vector_Create(); \ - \ + /*! \ + @brief Create an opaque pointer to a std::vector created from the \ + input raw array. The elements of the input array are deep copied before \ + inserting the copies into the vector. \ + @param len Number of elements in the input array. \ + @param elems A C array whose elements will be copied into the returned \ + vector. \ + @return Returns a new opaque pointer to a vector. \ + */ \ DPCTL_API \ __dpctl_give DPCTL##EL##VectorRef DPCTL##EL##Vector_CreateFromArray( \ size_t len, __dpctl_keep DPCTLSycl##EL##Ref *elems); \ \ + /*! \ + @brief Delete all elements in the vector and then delete the vector. \ + @param VRef Opaque pointer to a vector to be deleted. \ + */ \ DPCTL_API \ - void DPCTL##EL##Vector_Delete(__dpctl_take DPCTL##EL##VectorRef Ref); \ - \ + void DPCTL##EL##Vector_Delete(__dpctl_take DPCTL##EL##VectorRef VRef); \ + /*! \ + @brief Delete all the elements of the std::vector \ + @param VRef Opaque pointer to a vector. \ + */ \ DPCTL_API \ - void DPCTL##EL##Vector_Clear(__dpctl_keep DPCTL##EL##VectorRef Ref); \ - \ + void DPCTL##EL##Vector_Clear(__dpctl_keep DPCTL##EL##VectorRef VRef); \ + /*! \ + @brief Returns the number of elements in the vector. \ + @param VRef Opaque pointer to a vector. \ + @return The current size of the vector. \ + */ \ DPCTL_API \ - size_t DPCTL##EL##Vector_Size(__dpctl_keep DPCTL##EL##VectorRef Ref); \ - \ + size_t DPCTL##EL##Vector_Size(__dpctl_keep DPCTL##EL##VectorRef VRef); \ + /*! \ + @brief Returns the element at the specified index. \ + @param VRef Opaque pointer to a vector. \ + @param index The index postion of the element to be returned. \ + @return The element at the specified postion, if the index position is \ + out of bounds then a nullptr is returned. \ + */ \ DPCTL_API \ __dpctl_give DPCTLSycl##EL##Ref DPCTL##EL##Vector_GetAt( \ - __dpctl_keep DPCTL##EL##VectorRef Ref, size_t index); + __dpctl_keep DPCTL##EL##VectorRef VRef, size_t index); #define DPCTL_DECLARE_VECTOR(EL) \ DPCTL_DECLARE_VECTOR_TYPE(EL) \ From 092f5b3e619e1169f375474344c23555f3108144 Mon Sep 17 00:00:00 2001 From: Diptorup Deb Date: Thu, 8 Apr 2021 21:27:33 -0500 Subject: [PATCH 2/2] Other minor C API doc fixes. --- .../include/dpctl_sycl_device_interface.h | 75 ++++++++++--------- 1 file changed, 38 insertions(+), 37 deletions(-) diff --git a/dpctl-capi/include/dpctl_sycl_device_interface.h b/dpctl-capi/include/dpctl_sycl_device_interface.h index be69f34447..819592fb1d 100644 --- a/dpctl-capi/include/dpctl_sycl_device_interface.h +++ b/dpctl-capi/include/dpctl_sycl_device_interface.h @@ -57,7 +57,8 @@ DPCTLDevice_Copy(__dpctl_keep const DPCTLSyclDeviceRef DRef); * @brief Returns a new DPCTLSyclDeviceRef opaque object wrapping a SYCL device * instance as a host device. * - * @return An opaque pointer to the host SYCL device. + * @return An opaque pointer to a ``sycl::device`` created as an instance of + * the host device. * @ingroup DeviceInterface */ DPCTL_API @@ -67,7 +68,7 @@ __dpctl_give DPCTLSyclDeviceRef DPCTLDevice_Create(); * @brief Returns a new DPCTLSyclDeviceRef opaque object created using the * provided device_selector. * - * @param DSRef An opaque pointer to a SYCL device_selector. + * @param DSRef An opaque pointer to a ``sycl::device_selector``. * @return Returns an opaque pointer to a SYCL device created using the * device_selector, if the requested device could not be created a * nullptr is returned. @@ -88,9 +89,9 @@ void DPCTLDevice_Delete(__dpctl_take DPCTLSyclDeviceRef DRef); /*! * @brief Returns true if this SYCL device is an OpenCL device and the device - * type is sycl::info::device_type::accelerator. + * type is ``sycl::info::device_type::accelerator``. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return True if the device type is an accelerator, else False. * @ingroup DeviceInterface */ @@ -99,9 +100,9 @@ bool DPCTLDevice_IsAccelerator(__dpctl_keep const DPCTLSyclDeviceRef DRef); /*! * @brief Returns true if this SYCL device is an OpenCL device and the device - * type is sycl::info::device_type::cpu. + * type is ``sycl::info::device_type::cpu``. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return True if the device type is a cpu, else False. * @ingroup DeviceInterface */ @@ -110,9 +111,9 @@ bool DPCTLDevice_IsCPU(__dpctl_keep const DPCTLSyclDeviceRef DRef); /*! * @brief Returns true if this SYCL device is an OpenCL device and the device - * type is sycl::info::device_type::gpu. + * type is ``sycl::info::device_type::gpu``. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return True if the device type is a gpu, else False. * @ingroup DeviceInterface */ @@ -122,7 +123,7 @@ bool DPCTLDevice_IsGPU(__dpctl_keep const DPCTLSyclDeviceRef DRef); /*! * @brief Returns true if this SYCL device is a host device. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return True if the device is a host device, else False. * @ingroup DeviceInterface */ @@ -132,9 +133,9 @@ bool DPCTLDevice_IsHost(__dpctl_keep const DPCTLSyclDeviceRef DRef); /*! * @brief Returns the backend for the device. * - * @param DRef Opaque pointer to a sycl::device - * @return A DPCTLSyclBackendType enum value representing the sycl::backend - * for the device. + * @param DRef Opaque pointer to a ``sycl::device`` + * @return A DPCTLSyclBackendType enum value representing the + * ``sycl::backend`` for the device. * @ingroup DeviceInterface */ DPCTL_API @@ -156,7 +157,7 @@ DPCTLDevice_GetDeviceType(__dpctl_keep const DPCTLSyclDeviceRef DRef); /*! * @brief Returns the OpenCL software driver version as a C string. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return A C string in the form major_number.minor.number that corresponds * to the OpenCL driver version if this is a OpenCL device. * @ingroup DeviceInterface @@ -168,7 +169,7 @@ DPCTLDevice_GetDriverInfo(__dpctl_keep const DPCTLSyclDeviceRef DRef); /*! * @brief Wrapper over device.get_info(). * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return Returns the valid result if device exists else returns 0. * @ingroup DeviceInterface */ @@ -179,7 +180,7 @@ DPCTLDevice_GetMaxComputeUnits(__dpctl_keep const DPCTLSyclDeviceRef DRef); /*! * @brief Wrapper for get_info(). * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return Returns the valid result if device exists else returns 0. * @ingroup DeviceInterface */ @@ -190,7 +191,7 @@ DPCTLDevice_GetMaxWorkItemDims(__dpctl_keep const DPCTLSyclDeviceRef DRef); /*! * @brief Wrapper for get_info(). * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return Returns the valid result if device exists else returns NULL. * @ingroup DeviceInterface */ @@ -201,7 +202,7 @@ DPCTLDevice_GetMaxWorkItemSizes(__dpctl_keep const DPCTLSyclDeviceRef DRef); /*! * @brief Wrapper for get_info(). * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return Returns the valid result if device exists else returns 0. * @ingroup DeviceInterface */ @@ -212,7 +213,7 @@ DPCTLDevice_GetMaxWorkGroupSize(__dpctl_keep const DPCTLSyclDeviceRef DRef); /*! * @brief Wrapper over device.get_info. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return Returns the valid result if device exists else returns 0. * @ingroup DeviceInterface */ @@ -221,10 +222,10 @@ uint32_t DPCTLDevice_GetMaxNumSubGroups(__dpctl_keep const DPCTLSyclDeviceRef DRef); /*! - * @brief Returns the sycl::platform for the device as DPCTLSyclPlatformRef + * @brief Returns the ``sycl::platform`` for the device as DPCTLSyclPlatformRef * opaque pointer. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return An opaque pointer to the sycl::platform for the device. * @ingroup DeviceInterface */ @@ -235,7 +236,7 @@ DPCTLDevice_GetPlatform(__dpctl_keep const DPCTLSyclDeviceRef DRef); /*! * @brief Returns a C string for the device name. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return A C string containing the OpenCL device name. * @ingroup DeviceInterface */ @@ -246,7 +247,7 @@ DPCTLDevice_GetName(__dpctl_keep const DPCTLSyclDeviceRef DRef); /*! * @brief Returns a C string corresponding to the vendor name. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return A C string containing the OpenCL device vendor name. * @ingroup DeviceInterface */ @@ -258,7 +259,7 @@ DPCTLDevice_GetVendorName(__dpctl_keep const DPCTLSyclDeviceRef DRef); * @brief Returns True if the device and the host share a unified memory * subsystem, else returns False. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return Boolean indicating if the device shares a unified memory subsystem * with the host. * @ingroup DeviceInterface @@ -271,8 +272,8 @@ bool DPCTLDevice_IsHostUnifiedMemory( * @brief Checks if two DPCTLSyclDeviceRef objects point to the same * sycl::device. * - * @param DRef1 First opaque pointer to a sycl device. - * @param DRef2 Second opaque pointer to a sycl device. + * @param DRef1 First opaque pointer to a ``sycl::device``. + * @param DRef2 Second opaque pointer to a ``sycl::device``. * @return True if the underlying sycl::device are same, false otherwise. * @ingroup DeviceInterface */ @@ -283,8 +284,8 @@ bool DPCTLDevice_AreEq(__dpctl_keep const DPCTLSyclDeviceRef DRef1, /*! * @brief Checks if device has aspect. * - * @param DRef Opaque pointer to a sycl::device - * @param AT DPCTLSyclAspectType of device::aspect. + * @param DRef Opaque pointer to a ``sycl::device`` + * @param AT DPCTLSyclAspectType of ``device::aspect``. * @return True if sycl::device has device::aspect, else false. * @ingroup DeviceInterface */ @@ -391,7 +392,7 @@ DPCTLDevice_GetImage3dMaxDepth(__dpctl_keep const DPCTLSyclDeviceRef DRef); * units is not evenly divided by count, then the remaining compute units are * not included in any of the sub devices. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @param count Count compute units that need to contains in * subdevices * @return A #DPCTLDeviceVectorRef containing #DPCTLSyclDeviceRef objects @@ -408,7 +409,7 @@ DPCTLDevice_CreateSubDevicesEqually(__dpctl_keep const DPCTLSyclDeviceRef DRef, * non-zero value M in the counts vector, a sub device with M compute units * is created. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @param counts Array with count compute units * that need to contains in subdevices * @param ncounts Number of counts @@ -457,7 +458,7 @@ bool DPCTLDevice_GetSubGroupIndependentForwardProgress( * @brief Wrapper over * device.get_info. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return Returns the preferred native vector width size for built-in scalar * types that can be put into vectors. * @ingroup DeviceInterface @@ -470,7 +471,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthChar( * @brief Wrapper over * device.get_info. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return Returns the preferred native vector width size for built-in scalar * types that can be put into vectors. * @ingroup DeviceInterface @@ -483,7 +484,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthShort( * @brief Wrapper over * device.get_info. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return Returns the preferred native vector width size for built-in scalar * types that can be put into vectors. * @ingroup DeviceInterface @@ -496,7 +497,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthInt( * @brief Wrapper over * device.get_info. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return Returns the preferred native vector width size for built-in scalar * types that can be put into vectors. * @ingroup DeviceInterface @@ -509,7 +510,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthLong( * @brief Wrapper over * device.get_info. * - * @param DRef Opaque pointer + * @param DRef Opaque pointer to a ``sycl::device`` * @return Returns the preferred native vector width size for built-in scalar * type. * @ingroup DeviceInterface @@ -522,7 +523,7 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthFloat( * @brief Wrapper over * device.get_info. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return Returns the preferred native vector width size for built-in scalar * types that can be put into vectors. * @ingroup DeviceInterface @@ -533,9 +534,9 @@ uint32_t DPCTLDevice_GetPreferredVectorWidthDouble( /*! * @brief Wrapper over - * device.get_info. + * ``device.get_info``. * - * @param DRef Opaque pointer to a sycl::device + * @param DRef Opaque pointer to a ``sycl::device`` * @return Returns the preferred native vector width size for built-in scalar * types that can be put into vectors. * @ingroup DeviceInterface