|
| 1 | +| Proposal ID | TBC | |
| 2 | +|-------------|--------| |
| 3 | +| Name | | |
| 4 | +| Date of Creation | 16 January 2019 | |
| 5 | +| Target | Vendor extension | |
| 6 | +| Current Status | _Work in progress_ | |
| 7 | +| Reply-to | Victor Lomüller <victor@codeplay.com> | |
| 8 | +| Original author | Victor Lomüller <victor@codeplay.com>, Gordon Brown <gordon@codeplay.com>, Peter Zuzek <peter@codeplay.com> | |
| 9 | +| Contributors | Victor Lomüller <victor@codeplay.com>, Gordon Brown <gordon@codeplay.com>, Peter Zuzek <peter@codeplay.com> | |
| 10 | + |
| 11 | +# interop_task: Improving SYCL-OpenCL Interoperability |
| 12 | + |
| 13 | +## Motivation |
| 14 | + |
| 15 | +SYCL does not allow a user to access cl_mem object out of an cl::sycl::accessor, it is difficult to integrate low-level API functionality inside the data-flow execution model of SYCL, as the only current way to do this is to create all OpenCL buffers up-front, which is not always possible. |
| 16 | + |
| 17 | +This proposal introduces a way for a user to retrieve the low-level objects associated with SYCL buffers and enqueue a host task that can execute an arbitrary portion of host code within the SYCL runtime, therefore taking advantage of SYCL dependency analysis and scheduling. |
| 18 | + |
| 19 | +## Accessing low-level API functionality on SYCL queues |
| 20 | + |
| 21 | +We introduce a new type of handler, the **codeplay::handler**, which includes a new |
| 22 | +**interop\_task** method that enables submission of low-level API code from the host. |
| 23 | +By submitting this command group to the SYCL device queue, we guarantee it is |
| 24 | +executed in-order w.r.t the other command groups on the same queue. |
| 25 | +Simultaneously, we guarantee that this operation is performed |
| 26 | +asynchronously w.r.t to the user-thread (therefore, enabling the user |
| 27 | +thread to continue submitting command groups). |
| 28 | +Other command groups enqueued in the same or different queues |
| 29 | +can be executed following the sequential consistency by guaranteeing the |
| 30 | +satisfaction of the requisites of this command group. |
| 31 | +It is the user's responsibility to ensure the lambda submitted via interop_task does not create race conditions with other command groups or with the host. |
| 32 | + |
| 33 | +The possibility of enqueuing host tasks on SYCL queues also enables the |
| 34 | +runtime to perform further optimizations when available. |
| 35 | +For example, a SYCL runtime may decide to map / unmap instead of performing copy operations, |
| 36 | +or perform asynchronous transfers while data is being computed. |
| 37 | + |
| 38 | +### cl::sycl::codeplay::handler |
| 39 | + |
| 40 | +```cpp |
| 41 | +namespace cl { |
| 42 | +namespace sycl { |
| 43 | +namespace codeplay { |
| 44 | + |
| 45 | +class handler : public cl::sycl::handler { |
| 46 | + private: |
| 47 | + // implementation defined constructor |
| 48 | + handler(__unspecified__); |
| 49 | + |
| 50 | + public: |
| 51 | + /* Submit a task with interoperability statements. */ |
| 52 | + template <typename FunctorT> |
| 53 | + void interop_task(FunctorT hostFunction); |
| 54 | +}; |
| 55 | +} // namespace codeplay |
| 56 | +} // namespace sycl |
| 57 | +} // namespace cl |
| 58 | +``` |
| 59 | +
|
| 60 | +### codeplay::handler::interop_task |
| 61 | +
|
| 62 | +The `interop_task` allows users to submit tasks containing C++ statements with low-level API calls (e.g. OpenCL Host API entries). |
| 63 | +The command group that encapsulates the task will execute following the usual SYCL dataflow execution rules. |
| 64 | +The functor passed to the `interop_task` takes as input a const reference to a `cl::sycl::codeplay::interop_handle`. The handle can be used to retrieve underlying OpenCL objects relative to the execution of the task. |
| 65 | +
|
| 66 | +It is not allowed to allocate new SYCL object inside an `interop_task`. |
| 67 | +It is the user's responsibility to ensure that all operations performed inside the `interop_task` are finished before returning from it. |
| 68 | +
|
| 69 | +Although the statements inside the lambda submitted to the `interop_task` are executed on the host, the requirements and actions for the command group are satisied for the device. |
| 70 | +This is the opposite of the `host_handler` vendor extension, where requisites are satisfied for the host since the statements on the lambda submited to the single task are meant to have side effects on the host only. |
| 71 | +The interop task lambda can have side effects on the host, but it is the programmer responsability to ensure requirements dont need to be satisfied for the host. |
| 72 | +
|
| 73 | +## Accessing low-level API objects |
| 74 | +
|
| 75 | +We introduce the `interop_handle` class which provide access to underlying OpenCL objects during the execution of the `interop_task`. |
| 76 | +`interop_handle` objects are immutable objects whose purpose is to enable users access to low-level API functionality. |
| 77 | +
|
| 78 | +The interface of the `interop_handle` is defined as follow: |
| 79 | +```cpp |
| 80 | +namespace cl { |
| 81 | +namespace sycl { |
| 82 | +namespace codeplay { |
| 83 | +
|
| 84 | +class interop_handle { |
| 85 | + private: |
| 86 | + // implementation defined constructor |
| 87 | + interop_handle(__unspecified__); |
| 88 | +
|
| 89 | + public: |
| 90 | + /* Return the context */ |
| 91 | + cl_context get_context() const; |
| 92 | +
|
| 93 | + /* Return the device id */ |
| 94 | + cl_device_id get_device() const; |
| 95 | +
|
| 96 | + /* Return the command queue associated with this task */ |
| 97 | + cl_command_queue get_queue() const; |
| 98 | +
|
| 99 | + /* |
| 100 | + Returns the underlying cl_mem object associated with a given accessor |
| 101 | + */ |
| 102 | + template <typename dataT, int dimensions, access::mode accessmode, |
| 103 | + access::target accessTarget, |
| 104 | + access::placeholder isPlaceholder> |
| 105 | + cl_mem get_buffer(const accessor<dataT, dimensions, accessmode, access::target accessTarget, access::placeholder isPlaceholder>&) const; |
| 106 | +}; |
| 107 | +} // namespace codeplay |
| 108 | +} // namespace sycl |
| 109 | +} // namespace cl |
| 110 | +``` |
| 111 | + |
| 112 | +## Example using regular accessor |
| 113 | + |
| 114 | +```cpp |
| 115 | + auto cgH = [=] (codeplay::handler& cgh) { |
| 116 | + // Get device accessor to SYCL buffer (cannot be dereferenced directly in interop_task). |
| 117 | + auto accA = bufA.get_access<access::mode::read>(cgh); |
| 118 | + auto accB = bufB.get_access<access::mode::read_write>(cgh); |
| 119 | + |
| 120 | + h.interop_task([=](codeplay::interop_handle &handle) { |
| 121 | + third_party_api(handle.get_queue(), // Get the OpenCL command queue to use, can be the fallback |
| 122 | + handle.get_buffer(accA), // Get the OpenCL mem object behind accA |
| 123 | + handle.get_buffer(accB)); // Get the OpenCL mem object behind accB |
| 124 | + // Assumes call has finish when exiting the task |
| 125 | + }); |
| 126 | + }; |
| 127 | + qA.submit(cgH); |
| 128 | +``` |
| 129 | +
|
| 130 | +This example calls the clFFT library from SYCL using the `interop_task`: |
| 131 | +```cpp |
| 132 | +#include <stdlib.h> |
| 133 | +#include <CL/sycl.hpp> |
| 134 | +
|
| 135 | +/* No need to explicitly include the OpenCL headers */ |
| 136 | +#include <clFFT.h> |
| 137 | +
|
| 138 | +int main( void ) |
| 139 | +{ |
| 140 | + size_t N = 16; |
| 141 | +
|
| 142 | + cl::sycl::queue device_queue; |
| 143 | + cl::sycl::buffer<float> X(range<1>(N * 2)); |
| 144 | +
|
| 145 | + /* Setup clFFT. */ |
| 146 | + clfftSetupData fftSetup; |
| 147 | + err = clfftInitSetupData(&fftSetup); |
| 148 | + err = clfftSetup(&fftSetup); |
| 149 | +
|
| 150 | + device_queue.submit([=](codeplay::handler& cgh) { |
| 151 | + auto X_accessor = X.get_access<access::mode::read_write>(cgh); |
| 152 | + h.interop_task([=](codeplay::interop_handle &handle) { |
| 153 | + /* FFT library related declarations */ |
| 154 | + clfftPlanHandle planHandle; |
| 155 | + size_t clLengths[1] = {N}; |
| 156 | +
|
| 157 | + /* Create a default plan for a complex FFT. */ |
| 158 | + err = clfftCreateDefaultPlan(&planHandle, handle.get_context(), CLFFT_1D, clLengths); |
| 159 | +
|
| 160 | + /* Set plan parameters. */ |
| 161 | + err = clfftSetPlanPrecision(planHandle, CLFFT_SINGLE); |
| 162 | + err = clfftSetLayout(planHandle, CLFFT_COMPLEX_INTERLEAVED, CLFFT_COMPLEX_INTERLEAVED); |
| 163 | + err = clfftSetResultLocation(planHandle, CLFFT_INPLACE); |
| 164 | +
|
| 165 | + /* Bake the plan. */ |
| 166 | + err = clfftBakePlan(planHandle, 1, &queue, NULL, NULL); |
| 167 | +
|
| 168 | + /* Execute the plan. */ |
| 169 | + cl_command_queue queue = handle.get_queue(); |
| 170 | + cl_mem X_mem = handle.get_buffer(X_accessor); |
| 171 | + err = clfftEnqueueTransform(planHandle, CLFFT_FORWARD, |
| 172 | + 1, &queue, 0, NULL, NULL, |
| 173 | + &X_mem, NULL, NULL); |
| 174 | +
|
| 175 | + /* Wait for calculations to finish. */ |
| 176 | + err = clFinish(queue); |
| 177 | +
|
| 178 | + /* Release the plan. */ |
| 179 | + err = clfftDestroyPlan( &planHandle ); |
| 180 | + }); |
| 181 | + }); |
| 182 | +
|
| 183 | + /* Release clFFT library. */ |
| 184 | + clfftTeardown( ); |
| 185 | +
|
| 186 | + return 0; |
| 187 | +} |
| 188 | +``` |
0 commit comments