[SYCL][DOC] Initial Draft of Extension for querying free device memory on Level Zero #3468
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||
|---|---|---|---|---|---|---|---|---|
|
|
@@ -139,9 +139,48 @@ Applications must make sure that the Level-Zero handles themselves aren't used s | |||||||
| Practically speaking, and taking into account that SYCL runtime takes ownership of the Level-Zero handles, | ||||||||
| the application should not attempt further direct use of those handles. | ||||||||
|
|
||||||||
| ## 5 Level-Zero additional functionality | ||||||||
|
|
||||||||
| ### 5.1 Free Memory query | ||||||||
| Level Zero contains a library for system resource management called Sysman. | ||||||||
| Sysman allows programmers to query the amount of free, or unallocated, | ||||||||
| memory in a device. This extension provides a new device information | ||||||||
| descriptor specific to Level-Zero Backends that allows DPC++ programs to query | ||||||||
| the amount of free memory for a given device. The new descriptor is as follows: | ||||||||
jbrodman marked this conversation as resolved.
Outdated
Show resolved
Hide resolved
|
||||||||
|
|
||||||||
| ``` C++ | ||||||||
| namespace sycl{ | ||||||||
| namespace ext { | ||||||||
| namespace oneapi{ | ||||||||
| namespace level_zero { | ||||||||
| namespace info { | ||||||||
| namespace device { | ||||||||
|
|
||||||||
| struct free_memory { | ||||||||
| using return_type = size_t; | ||||||||
| }; | ||||||||
|
|
||||||||
| } // namespace device; | ||||||||
| } // namespace info | ||||||||
| } // namespace level_zero | ||||||||
| } // namespace oneapi | ||||||||
| } // namespace ext | ||||||||
| } // namespace sycl | ||||||||
| ``` | ||||||||
|
|
||||||||
| The new struct ```free_memory``` is used in conjuction with the ```get_backend_info()``` method of the ```device``` class in SYCL 2020. The query will return the number of bytes of free memory for that device. | ||||||||
|
||||||||
|
|
||||||||
| ``` C++ | ||||||||
| sycl::queue Queue; | ||||||||
| auto Device = Queue.get_device(); | ||||||||
|
|
||||||||
| uint64_t freeMemory = Device.get_backend_info<sycl::ext::oneapi::info::device::free_memory>(); | ||||||||
|
||||||||
| uint64_t freeMemory = Device.get_backend_info<sycl::ext::oneapi::info::device::free_memory>(); | |
| uint64_t freeMemory = Device.get_backend_info<sycl::ext::oneapi::level_zero::info::device::free_memory>(); | |
There was a problem hiding this comment.
@gmlueck Do you think we need the extra level_zero here?
There was a problem hiding this comment.
Yes, I think we need it. Why do you say it is "extra"? It's the only occurrence of "level_zero" in that statement.
There was a problem hiding this comment.
extra in the sense of "in addition to oneapi::"
There was a problem hiding this comment.
Let's take this as an opportunity to define the namespace for the Level Zero backend. The namspace naming convention for a SYCL extension is sycl::ext::<vendorstring>. We've decided that we have two <vendorstrings>: oneapi and intel, depending on whether the extension is tightly tied to Intel hardware vs. a general extension that we'd like promote into the SYCL spec someday.
At present the Level Zero backend is our own extension because we haven't attempted to add this backend to the SYCL spec in the same way as the OpenCL backend. Therefore, I think it needs to follow the extension naming guidelines. (Note, I'm just talking about the Level Zero backend to SYCL here, not Level Zero itself.)
Putting this together, we arrive at a namespace of sycl::ext::oneapi::level_zero.
However, I admit that is a mouthful. If we wanted to make it shorter, one option would be to add another <vendorstring> and say that level_zero is itself a <vendorstring>. This would shorten the namespace to sycl::ext::level_zero.
Now let's consider the naming guidelines for new enumerated constants or new member functions that an extension adds. The guideline says that these should start with a prefix ext_<vendorstring>. There's no particular guideline for including the name of the backend, but it seems wise to somehow include the name "level_zero" if the API is tied to Level Zero. We can imagine that Level Zero might want to add some new aspects at some point, and of course Level Zero will have an enumerated constant in the sycl::backend enum. Here's a comparison of how those would look using each of the two <vendorstrings> above:
// Vendor string is "oneapi"
namespace sycl {
enum class aspect {
// ...
ext_oneapi_level_zero_fancy
};
enum class backend {
// ...
ext_oneapi_level_zero
}:
} // namespace sycl
// Vendor string is "level_zero"
namespace sycl {
enum class aspect {
// ...
ext_level_zero_fancy
};
enum class backend {
// ...
ext_level_zero
}:
} // namespace sycl
There was a problem hiding this comment.
We still need to resolve this naming convention.
Uh oh!
There was an error while loading. Please reload this page.