1 /******************************************************************************* 2 * Copyright 2020 Intel Corporation 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 *******************************************************************************/ 16 17 #ifndef ONEAPI_DNNL_DNNL_SYCL_H 18 #define ONEAPI_DNNL_DNNL_SYCL_H 19 20 #include "oneapi/dnnl/dnnl.h" 21 22 #include "oneapi/dnnl/dnnl_sycl_types.h" 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 /// @addtogroup dnnl_api 29 /// @{ 30 31 /// @addtogroup dnnl_api_interop 32 /// @{ 33 34 /// @addtogroup dnnl_api_sycl_interop 35 /// @{ 36 37 /// Creates an engine associated with a SYCL device and a SYCL context. 38 /// 39 /// @param engine Output engine. 40 /// @param device Pointer to the SYCL device to use for the engine. 41 /// @param context Pointer to the SYCL context to use for the engine. 42 /// @returns #dnnl_success on success and a status describing the error 43 /// otherwise. 44 dnnl_status_t DNNL_API dnnl_sycl_interop_engine_create( 45 dnnl_engine_t *engine, const void *device, const void *context); 46 47 /// Returns the SYCL context associated with an engine. 48 /// 49 /// @param engine Engine to query. 50 /// @param context Pointer to the underlying SYCL context of the engine. 51 /// @returns #dnnl_success on success and a status describing the error 52 /// otherwise. 53 dnnl_status_t DNNL_API dnnl_sycl_interop_engine_get_context( 54 dnnl_engine_t engine, void **context); 55 56 /// Returns the SYCL device associated with an engine. 57 /// 58 /// @param engine Engine to query. 59 /// @param device Pointer to the underlying SYCL device of the engine. 60 /// @returns #dnnl_success on success and a status describing the error 61 /// otherwise. 62 dnnl_status_t DNNL_API dnnl_sycl_interop_engine_get_device( 63 dnnl_engine_t engine, void **device); 64 65 /// Creates a memory object. 66 /// 67 /// Unless @p handle is equal to DNNL_MEMORY_NONE or DNNL_MEMORY_ALLOCATE, the 68 /// constructed memory object will have the underlying buffer set. In this 69 /// case, the buffer will be initialized as if: 70 /// - dnnl_memory_set_data_handle() had been called, if @p memory_kind is equal 71 /// to dnnl_sycl_interop_usm, or 72 /// - dnnl_sycl_interop_memory_set_buffer() has been called, if @p memory_kind 73 /// is equal to dnnl_sycl_interop_buffer. 74 /// 75 /// @param memory Output memory object. 76 /// @param memory_desc Memory descriptor. 77 /// @param engine Engine to use. 78 /// @param memory_kind Memory allocation kind to specify the type of handle. 79 /// @param handle Handle of the memory buffer to use as an underlying storage. 80 /// - A USM pointer to the user-allocated buffer. In this case the library 81 /// doesn't own the buffer. Requires @p memory_kind to be equal to 82 /// dnnl_sycl_interop_usm. 83 /// - A pointer to SYCL buffer. In this case the library doesn't own the 84 /// buffer. Requires @p memory_kind be equal to be equal to 85 /// dnnl_sycl_interop_buffer. 86 /// - The DNNL_MEMORY_ALLOCATE special value. Instructs the library to 87 /// allocate the buffer that corresponds to the memory allocation kind 88 /// @p memory_kind for the memory object. In this case the library 89 /// owns the buffer. 90 /// - The DNNL_MEMORY_NONE specific value. Instructs the library to 91 /// create memory object without an underlying buffer. 92 /// @returns #dnnl_success on success and a status describing the error 93 /// otherwise. 94 dnnl_status_t DNNL_API dnnl_sycl_interop_memory_create(dnnl_memory_t *memory, 95 const dnnl_memory_desc_t *memory_desc, dnnl_engine_t engine, 96 dnnl_sycl_interop_memory_kind_t memory_kind, void *handle); 97 98 /// Returns the memory allocation kind associated with a memory object. 99 /// 100 /// @param memory Memory to query. 101 /// @param memory_kind Output underlying memory allocation kind of the memory 102 /// object. 103 /// @returns #dnnl_success on success and a status describing the error 104 /// otherwise. 105 dnnl_status_t DNNL_API dnnl_sycl_interop_memory_get_memory_kind( 106 const_dnnl_memory_t memory, 107 dnnl_sycl_interop_memory_kind_t *memory_kind); 108 109 /// Sets a SYCL buffer for a memory object. 110 /// 111 /// @param memory Memory object. 112 /// @param buffer SYCL buffer to be set in the memory object. 113 /// @param stream Stream to use to execute padding in. 114 /// @returns #dnnl_success on success and a status describing the error 115 /// otherwise. 116 dnnl_status_t DNNL_API dnnl_sycl_interop_memory_set_buffer( 117 dnnl_memory_t memory, void *buffer, dnnl_stream_t stream); 118 119 /// Creates an execution stream for a given engine associated with a SYCL 120 /// queue. 121 /// 122 /// @param stream Output execution stream. 123 /// @param engine Engine to create the execution stream on. 124 /// @param queue SYCL queue to use. 125 /// @returns #dnnl_success on success and a status describing the error 126 /// otherwise. 127 dnnl_status_t DNNL_API dnnl_sycl_interop_stream_create( 128 dnnl_stream_t *stream, dnnl_engine_t engine, void *queue); 129 130 /// Returns the SYCL queue associated with an execution stream. 131 /// 132 /// @param stream Execution stream to query. 133 /// @param queue Output SYCL command queue. 134 /// @returns #dnnl_success on success and a status describing the error 135 /// otherwise. 136 dnnl_status_t DNNL_API dnnl_sycl_interop_stream_get_queue( 137 dnnl_stream_t stream, void **queue); 138 139 /// Executes computations specified by the primitive in a specified stream and 140 /// returns a SYCL event. 141 /// 142 /// @param primitive Primitive to execute. 143 /// @param stream Stream to use. 144 /// @param nargs Number of arguments. 145 /// @param args Array of arguments. Each argument is an 146 /// <index, #dnnl_memory_t> pair. The index is one of the `DNNL_ARG_*` 147 /// values such as `DNNL_ARG_SRC`. Unless runtime shapes are used (see 148 /// #DNNL_RUNTIME_DIM_VAL), the memory object must have the same memory 149 /// descriptor as that returned by 150 /// #dnnl_primitive_desc_query_md(#dnnl_query_exec_arg_md, index). 151 /// @param deps A pointer to std::vector<sycl::event> that contains 152 /// dependencies. 153 /// @param return_event Output event. 154 /// @returns #dnnl_success on success and a status describing the error 155 /// otherwise. 156 dnnl_status_t DNNL_API dnnl_sycl_interop_primitive_execute( 157 const_dnnl_primitive_t primitive, dnnl_stream_t stream, int nargs, 158 const dnnl_exec_arg_t *args, const void *deps, void *return_event); 159 160 /// @} dnnl_api_sycl_interop 161 162 /// @} dnnl_api_interop 163 164 /// @} dnnl_api 165 166 #ifdef __cplusplus 167 } 168 #endif 169 170 #endif 171