Docs for API tracing feature

Change-Id: Ibfc77ff0133b9f416b15f39c0241ae789376a285

Author: anton-v-gorshkov

runtime/tracing/tracing_api.h

@@ -13,12 +13,72 @@
 extern "C" {
 #endif
 
+/*!
+    Function creates a tracing handle object
+    \param[in] device Device to create tracing handle for
+    \param[in] callback User-defined callback that will be called along with
+                        traced API function
+    \param[in] userData Pointer to any data user would like to pass into the
+                        callback, can be zero
+    \param[out] handle Tracing handle object that describes current tracing
+                       session
+    \return Status code for current operation
+
+    Thread Safety: yes
+*/
 cl_int CL_API_CALL clCreateTracingHandleINTEL(cl_device_id device, cl_tracing_callback callback, void *userData, cl_tracing_handle *handle);
+
+/*!
+    Function allows to specify which target API call should be traced.
+    By default function will NOT be traced
+    \param[in] handle Tracing handle object
+    \param[in] fid Target function identifier
+    \param[in] enable Flag to enable/disable tracing for target function
+    \return Status code for current operation
+
+    Thread Safety: no
+*/
 cl_int CL_API_CALL clSetTracingPointINTEL(cl_tracing_handle handle, cl_function_id fid, cl_bool enable);
+
+/*!
+    Function destroys the tracing handle object and releases all the associated
+    resources
+    \param[in] handle Tracing handle object
+    \return Status code for current operation
+
+    Thread Safety: no
+*/
 cl_int CL_API_CALL clDestroyTracingHandleINTEL(cl_tracing_handle handle);
 
+/*!
+    Function enables the tracing process for the handle. Multiple handles
+    can be enabled at a time
+    \param[in] handle Tracing handle object
+    \return Status code for current operation
+
+    Thread Safety: yes
+*/
 cl_int CL_API_CALL clEnableTracingINTEL(cl_tracing_handle handle);
+
+/*!
+    Function disables the tracing process for the handle. It will wait until
+    all currently running callbacks are done
+    \param[in] handle Tracing handle object
+    \return Status code for current operation
+
+    Thread Safety: yes
+*/
 cl_int CL_API_CALL clDisableTracingINTEL(cl_tracing_handle handle);
+
+/*!
+    Function requests the tracing state for the handle
+    \param[in] handle Tracing handle object
+    \param[out] enable Returns TRUE if tracing handle is in use and
+                       FALSE otherwise
+    \return Status code for current operation
+
+    Thread Safety: yes
+*/
 cl_int CL_API_CALL clGetTracingStateINTEL(cl_tracing_handle handle, cl_bool *enable);
 
 #ifdef __cplusplus

runtime/tracing/tracing_types.h

@@ -13,20 +13,38 @@
 struct _cl_tracing_handle;
 typedef _cl_tracing_handle *cl_tracing_handle;
 
+//! Enumeration of callback call sites
 typedef enum _cl_callback_site {
-    CL_CALLBACK_SITE_ENTER = 0,
-    CL_CALLBACK_SITE_EXIT = 1
+    CL_CALLBACK_SITE_ENTER = 0, //!< Before the function
+    CL_CALLBACK_SITE_EXIT = 1   //!< After the function
 } cl_callback_site;
 
+/*!
+    \brief Callback data structure
+
+    The structure contains information about the traced function.
+    Function name allows to determine which function is currently traced.
+    Call site is used to determine if the callback was called at the beginning
+    or at the end of function.
+    Correlation ID and Data fields allow to associate the callback on
+    enter with the callback on exit and pass any piece of data between them.
+    Function arguments and return value available both for reading and writing.
+    Return value will be available only within on-exit callback
+*/
 typedef struct _cl_callback_data {
-    cl_callback_site site;
-    cl_uint correlationId;
-    cl_ulong *correlationData;
-    const char *functionName;
-    const void *functionParams;
-    void *functionReturnValue;
+    cl_callback_site site;      //!< Call site, can be ENTER or EXIT
+    cl_uint correlationId;      //!< Correlation identifier, the same for ENTER
+                                //!< and EXIT callbacks
+    cl_ulong *correlationData;  //!< Pointer to correlation data repository,
+                                //!< can be used to move data from ENTER to
+                                //!< EXIT callback
+    const char *functionName;   //!< Name of the traced function
+    const void *functionParams; //!< Traced function arguments, should be
+                                //!< casted to appropriate params structure
+    void *functionReturnValue;  //!< Return value for the traced function
 } cl_callback_data;
 
+//! Enumeration of supported functions for tracing
 typedef enum _cl_function_id {
     CL_FUNCTION_clBuildProgram = 0,
     CL_FUNCTION_clCloneKernel = 1,
@@ -149,6 +167,16 @@ typedef enum _cl_function_id {
     CL_FUNCTION_COUNT = 118,
 } cl_function_id;
 
+/*!
+    User-defined tracing callback prototype
+    \param[in] fid Identifier of the function for which the callback is called
+    \param[in] callbackData Data structure with information about the traced
+                            function
+    \param[in] userData User-defined data pointer passed through
+                        clCreateTracingHandleINTEL() function
+
+	Thread Safety: must be guaranteed by customer
+*/
 typedef void (*cl_tracing_callback)(cl_function_id fid, cl_callback_data *callbackData, void *userData);
 
 typedef struct _cl_params_clBuildProgram {