[SYCL] Document the SYCL Runtime Plugin Interface. #206
Conversation
sycl/doc/SYCLPluginInterface.md
Outdated
| piGetEventProfilingInfo | ||
| piFlush | ||
| piFinish | ||
| piEnqueueReadBuffer |
There was a problem hiding this comment.
I could be wrong or misunderstanding it, but I think this list is missing some of the calls from the pi.h interface (it may be intentional though as its the minimal subset, this comment can be disregarded then). For example piEnqueueReadBufferRect, piEnqueueWriteBufferRect and piEnqueueCopyBufferRect which are used for handling 2d/3d buffer transfers.
There was a problem hiding this comment.
Should we maybe avoid this duplication then and maintain APIs in one place - pi.h? Opinions?
There was a problem hiding this comment.
I think just directing people to the relevant place to find the plugin interface (pi.h) and giving an example interface call would work, so they know what they're looking for. It means you wouldn't have to maintain the list in the .md every time pi.h changed.
There was a problem hiding this comment.
Doxygen or similar could be used to generate a more readable documentation directly from the headers
There was a problem hiding this comment.
It means you wouldn't have to maintain the list in the .md every time pi.h changed.
Right, that's what I meant by avoiding duplication. Will remove most of the APIs and leave just few examples.
Doxygen or similar could be used to generate a more readable documentation directly from the headers
Good idea. Should be doxygen, I think, to be compatible with llvm/clang. We can start with maintaining doxygen in the pi.h
|
Thanks for providing the SVG of the images. :-) |
This is just a lack of experience with Open Source tools. Looks like .md viewers can show directly SVG :-) Will remove PNG. |
|
@Ruyk , @agozillon - can someone please comment or give an approve if this version seems OK? |
|
@agozillon - thanks. |
| to the device specific runtime layers similarly to what is used by libomptarget | ||
| or OpenCL. | ||
|
|
||
|  |
There was a problem hiding this comment.
I think we can make this picture clearer by removing components not related to the SYCL runtime plug-in interface.
E.g. TBB/OpenMP, all SYCL runtime components except PI related component.
Please, add legend clarifying the difference between solid and dotted lines.
Not sure how important is to have "host device" on this picture, but if you decide to not remove it, please, update SYCL runtime library component name.
"Host device RT interace" -> "Host device RT interface".
It would be great if can highlight that "PI interface" != "Host device RT interface".
Please, stretch out the image to fill the canvas. All images look smaller than they can be.
There was a problem hiding this comment.
Some minor comments. Also, names should match the PI interface names in the various @smaslov-intel PR (more points in favor of a Doxygen-maintained documentation!)
| matches unless the differences are explicitly specified in this document. While | ||
| PI has roots in OpenCL, it does have many differences, and the gap is likely | ||
| to grow, for example in the areas of memory model and management, program | ||
| management. |
There was a problem hiding this comment.
After the (welcomed) latest changes to the naming scheme, is not so clear anymore which functions map 1:1 to OpenCL.
Maybe the document could contain the mapping down below?
There was a problem hiding this comment.
I'd expect (at least part of) PI<->OpenCL mapping is to evolve, so I suggest that instead every function in the pi.h is commented whether it has direct OpenCL couterpart or not.
|
@kbobrovs, please, upload updated version. |
kbobrovs
force-pushed
the
pi_doc
branch
2 times, most recently
from
3c4c9e0 to
8474c68
Compare
There was a problem hiding this comment.
LGTM.
I'd like @smaslov-intel and @Ruyk to confirm that all their comments are addressed, before merging this change.
|
@kbobrovs, could you rebase the patch to the tip of the sycl branch, please? |
Initial version of the SYCL runtime plugin interface document. The SYCL Runtime Plugin Interface (PI) is the interface layer between device-agnostic part of the SYCL runtime and the device-specific runtime layers which control execution on the device. It employs the plugin mechanism to bind to the device specific runtime layers similarly to what is used by libomptarget or OpenCL. Signed-off-by: Konstantin Bobrovsky konstantin.s.bobrovsky@intel.com
|
@bader , done |
There was a problem hiding this comment.
I have no issues committing this as is. @garimagu is working on incremental update to this, which should be available tomorrow.
|
@bader, is there anything which prevents this PR from merging? |
|
@kbobrovs, yes. |
|
Those changes were fixed and committed. @sergey-semenov, please confirm/approve |
The SYCL Runtime Plugin Interface (PI) is the interface layer between
device-agnostic part of the SYCL runtime and the device-specific runtime layers
which control execution on the device. It employs the “plugin” mechanism to bind
to the device specific runtime layers similarly to what is used by libomptarget
or OpenCL.
Signed-off-by: Konstantin Bobrovsky konstantin.s.bobrovsky@intel.com