diff --git a/mtapi_opencl_c/include/embb/mtapi/c/mtapi_opencl.h b/mtapi_opencl_c/include/embb/mtapi/c/mtapi_opencl.h index 0205367..e0379af 100644 --- a/mtapi_opencl_c/include/embb/mtapi/c/mtapi_opencl.h +++ b/mtapi_opencl_c/include/embb/mtapi/c/mtapi_opencl.h @@ -36,23 +36,157 @@ extern "C" { #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( - 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( - 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. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Error codeDescription
\c MTAPI_ERR_JOB_INVALIDThe \c job_id is not a valid job ID, i.e., no action was created for + * that ID or the action has been deleted.
\c MTAPI_ERR_ACTION_EXISTSThis action is already created.
\c MTAPI_ERR_ACTION_LIMITExceeded maximum number of actions allowed.
\c MTAPI_ERR_NODE_NOTINITThe calling node is not initialized.
\c MTAPI_ERR_UNKNOWNThe kernel could not be compiled or no OpenCL device was + * available.
+ * + * \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_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 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_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 */ );