mtapi_opencl_c: added doxygen documentation

mtapi_opencl_c/include/embb/mtapi/c/mtapi_opencl.h

@@ -36,23 +36,157 @@ extern "C" {
 #endif
 #endif
 
 
 
 
+/**
+ * \defgroup C_MTAPI_OPENCL MTAPI OpenCL Plugin
+ *
+ * \ingroup C_MTAPI_EXT
+ *
+ *
+ */
+
+
+/**
+ * Initializes the MTAPI OpenCL environment on a previously initialized MTAPI
+ * node.
+ *
+ * It must be called on all nodes using the MTAPI OpenCL plugin.
+ *
+ * Application software using MTAPI network must call
+ * mtapi_opencl_plugin_initialize() once per node. It is an error to call
+ * mtapi_opencl_plugin_initialize() multiple times
+ * from a given node, unless mtapi_opencl_plugin_finalize() is called in
+ * between.
+ *
+ * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is
+ * set to the appropriate error defined below.
+ * Error code                  | Description
+ * --------------------------- | ----------------------------------------------
+ * \c MTAPI_ERR_UNKNOWN        | MTAPI OpenCL couldn't be initialized.
+ *
+ * \see mtapi_opencl_plugin_finalize()
+ *
+ * \notthreadsafe
+ * \ingroup C_MTAPI_OPENCL
+ */
 void mtapi_opencl_plugin_initialize(
 void mtapi_opencl_plugin_initialize(
-  MTAPI_OUT mtapi_status_t* status
+  MTAPI_OUT mtapi_status_t* status     /**< [out] Pointer to error code,
+                                            may be \c MTAPI_NULL */
 );
 );
 
 
+/**
+ * Finalizes the MTAPI OpenCL environment on the local MTAPI node.
+ *
+ * It has to be called by each node using MTAPI OpenCL. It is an error to call
+ * mtapi_opencl_plugin_finalize() without first calling
+ * mtapi_opencl_plugin_initialize(). An MTAPI node can call
+ * mtapi_opencl_plugin_finalize() once for each call to
+ * mtapi_opencl_plugin_initialize(), but it is an error to call
+ * mtapi_opencl_plugin_finalize() multiple times from a given node
+ * unless mtapi_opencl_plugin_initialize() has been called prior to each
+ * mtapi_opencl_plugin_finalize() call.
+ *
+ * All network tasks that have not completed and that have been started on the
+ * node where mtapi_opencl_plugin_finalize() is called will be canceled
+ * (see mtapi_task_cancel()). mtapi_opencl_plugin_finalize() blocks until all
+ * tasks that have been started on the same node return. Tasks that execute
+ * actions on the node where mtapi_opencl_plugin_finalize() is called, also
+ * block finalization of the MTAPI OpenCL system on that node.
+ *
+ * On success, \c *status is set to \c MTAPI_SUCCESS. On error, \c *status is
+ * set to the appropriate error defined below.
+ * Error code                    | Description
+ * ----------------------------- | --------------------------------------------
+ * \c MTAPI_ERR_UNKNOWN          | MTAPI OpenCL couldn't be finalized.
+ *
+ * \see mtapi_opencl_plugin_initialize(), mtapi_task_cancel()
+ *
+ * \notthreadsafe
+ * \ingroup C_MTAPI_OPENCL
+ */
 void mtapi_opencl_plugin_finalize(
 void mtapi_opencl_plugin_finalize(
-  MTAPI_OUT mtapi_status_t* status
+  MTAPI_OUT mtapi_status_t* status     /**< [out] Pointer to error code,
+                                            may be \c MTAPI_NULL */
 );
 );
 
 
+/**
+ * This function creates an OpenCL action.
+ *
+ * It is called on the node where the user wants to execute an action on an
+ * OpenCL device. An OpenCL action contains a reference to a local job, the
+ * kernel source to compile and execute on the OpenCL device, the name of the
+ * kernel function, a local work size (see OpenCL specification for details)
+ * and the size of one element in the result buffer.
+ * After an OpenCL action is created, it is referenced by the application using
+ * a node-local handle of type \c mtapi_action_hndl_t, or indirectly through a
+ * node-local job handle of type \c mtapi_job_hndl_t. An OpenCL action's
+ * life-cycle begins with mtapi_opencl_action_create(), and ends when
+ * mtapi_action_delete() or mtapi_finalize() is called.
+ *
+ * To create an action, the application must supply the domain-wide job ID of
+ * the job associated with the action. Job IDs must be predefined in the
+ * application and runtime, of type \c mtapi_job_id_t, which is an
+ * implementation-defined type. The job ID is unique in the sense that it is
+ * unique for the job implemented by the action. However several actions may
+ * implement the same job for load balancing purposes.
+ *
+ * If \c node_local_data_size is not zero, \c node_local_data specifies the
+ * start of node local data shared by kernel functions executed on the same
+ * node. \c node_local_data_size can be used by the runtime for cache coherency
+ * operations.
+ *
+ * On success, an action handle is returned and \c *status is set to
+ * \c MTAPI_SUCCESS. On error, \c *status is set to the appropriate error
+ * defined below. In the case where the action already exists, \c status will
+ * be set to \c MTAPI_ERR_ACTION_EXISTS and the handle returned will not be a
+ * valid handle.
+ * <table>
+ *   <tr>
+ *     <th>Error code</th>
+ *     <th>Description</th>
+ *   </tr>
+ *   <tr>
+ *     <td>\c MTAPI_ERR_JOB_INVALID</td>
+ *     <td>The \c job_id is not a valid job ID, i.e., no action was created for
+ *         that ID or the action has been deleted.</td>
+ *   </tr>
+ *   <tr>
+ *     <td>\c MTAPI_ERR_ACTION_EXISTS</td>
+ *     <td>This action is already created.</td>
+ *   </tr>
+ *   <tr>
+ *     <td>\c MTAPI_ERR_ACTION_LIMIT</td>
+ *     <td>Exceeded maximum number of actions allowed.</td>
+ *   </tr>
+ *   <tr>
+ *     <td>\c MTAPI_ERR_NODE_NOTINIT</td>
+ *     <td>The calling node is not initialized.</td>
+ *   </tr>
+ *   <tr>
+ *     <td>\c MTAPI_ERR_UNKNOWN</td>
+ *     <td>The kernel could not be compiled or no OpenCL device was
+ *         available.</td>
+ *   </tr>
+ * </table>
+ *
+ * \see mtapi_action_delete(), mtapi_finalize()
+ *
+ * \returns Handle to newly created OpenCL action, invalid handle on error
+ * \threadsafe
+ * \ingroup C_MTAPI_OPENCL
+ */
 mtapi_action_hndl_t mtapi_opencl_action_create(
 mtapi_action_hndl_t mtapi_opencl_action_create(
-  MTAPI_IN mtapi_job_id_t job_id,
-  MTAPI_IN char* kernel_source,
-  MTAPI_IN char* kernel_name,
+  MTAPI_IN mtapi_job_id_t job_id,      /**< [in] Job id */
+  MTAPI_IN char* kernel_source,        /**< [in] Pointer to kernel source */
+  MTAPI_IN char* kernel_name,          /**< [in] Name of the kernel function */
   MTAPI_IN mtapi_size_t local_work_size,
   MTAPI_IN mtapi_size_t local_work_size,
-  MTAPI_IN mtapi_size_t element_size,
-  MTAPI_IN void* node_local_data,
+                                       /**< [in] Size of local work group */
+  MTAPI_IN mtapi_size_t element_size,  /**< [in] Size of one element in the
+                                            result buffer */
+  MTAPI_IN void* node_local_data,      /**< [in] Data shared across tasks */
   MTAPI_IN mtapi_size_t node_local_data_size,
   MTAPI_IN mtapi_size_t node_local_data_size,
-  MTAPI_OUT mtapi_status_t* status
+                                       /**< [in] Size of shared data */
+  MTAPI_OUT mtapi_status_t* status     /**< [out] Pointer to error code,
+                                            may be \c MTAPI_NULL */
 );
 );