From aadf152e83a7fa9685271ed0701ab87c5bfa43d8 Mon Sep 17 00:00:00 2001 From: tapplencourt Date: Thu, 12 Feb 2026 23:03:20 +0000 Subject: [PATCH 1/6] KHR extension --- adoc/extensions/index.adoc | 1 + adoc/extensions/sycl_khr_prefetch_host.adoc | 122 ++++++++++++++++++++ 2 files changed, 123 insertions(+) create mode 100644 adoc/extensions/sycl_khr_prefetch_host.adoc diff --git a/adoc/extensions/index.adoc b/adoc/extensions/index.adoc index d16bc954b..84f46f924 100644 --- a/adoc/extensions/index.adoc +++ b/adoc/extensions/index.adoc @@ -18,3 +18,4 @@ include::sycl_khr_queue_flush.adoc[leveloffset=2] include::sycl_khr_work_item_queries.adoc[leveloffset=2] include::sycl_khr_static_addrspace_cast.adoc[leveloffset=2] include::sycl_khr_dynamic_addrspace_cast.adoc[leveloffset=2] +include::sycl_khr_prefetch_host.adoc[leveloffset=2] diff --git a/adoc/extensions/sycl_khr_prefetch_host.adoc b/adoc/extensions/sycl_khr_prefetch_host.adoc new file mode 100644 index 000000000..d6e746713 --- /dev/null +++ b/adoc/extensions/sycl_khr_prefetch_host.adoc @@ -0,0 +1,122 @@ +[[sec:khr-prefetch-host]] += sycl_khr_prefetch_host + +This extension allows developers to prefetch data from the device to the host. + +[[sec:khr-prefetch-host-dependencies]] +== Dependencies + +This extension has no dependencies on other extensions. + +[[sec:khr-prefetch-host-feature-test]] +== Feature test macro + +An implementation supporting this extension must predefine the macro +[code]#SYCL_KHR_PREFETCH_HOST# to one of the values defined in the table below. + +[%header,cols="1,5"] +|=== +|Value +|Description + +|1 +|Initial version of this extension. +|=== + +[[sec:khr-prefetch-host-queue]] +== Extensions to the queue class + +This extension adds the following function to the [code]#sycl::handler# class. + +''' + +[source,role=synopsis,id=api:khr-prefetch-host-queue] +---- +namespace sycl { +class handler { + void khr_prefetch_host(); + // ... +}; +} +---- + +This extension adds the following function to the [code]#sycl::queue# class. + +''' + +[source,role=synopsis,id=api:khr-prefetch-host-queue] +---- +namespace sycl { +class queue { + event khr_prefetch_host(void* ptr, size_t numBytes); + event khr_prefetch_host(void* ptr, size_t numBytes, event depEvent); + event khr_prefetch_host(void* ptr, size_t numBytes, const std::vector& depEvents); + // ... +}; +} +---- + +[[sec:khr-prefetch-host-handle-menber-funcs]] +=== Member functions + +.[apidef]#handle::khr_prefetch_host# +[source,role=synopsis,id=api:handle-khr-prefetch-host] +---- +void khr_prefetch_host(void* ptr, size_t numBytes) +---- + +_Effects:_ Prefetches a number of elements specified by #[code]numElements# into +the host memory cache + +{note} This operation is an implementation-defined optimization and does not +effect the functional behavior of the SYCL kernel function. +{endnote} + +''' + +[[sec:khr-prefetch-host-queue-menber-funcs]] +=== Member functions + +.[apidef]#queue::khr_prefetch_host# +[source,role=synopsis,id=api:queue-khr-prefetch-host] +---- +event khr_prefetch_host(void* ptr, size_t numBytes) (1) + +event khr_prefetch_host(void* ptr, size_t numBytes, event depEvent) (2) + +event khr_prefetch_host(void* ptr, size_t numBytes, const std::vector& depEvents) (3) + +---- + +_Effects (1)_: Equivalent to calling #[code]queue::submit# with a command group +function that calls #[code]handler::khr_prefetch_host(ptr, numBytes)#. + +_Effects (2)_: Equivalent to calling #[code]queue::submit# with a command group +function that calls #[code]handler::depends_on(depEvent)# and +#[code]handler::khr_prefetch_host(ptr, numBytes)#. + +_Effects (3)_: Equivalent to calling #[code]queue::submit# with a command group +function that calls #[code]handler::depends_on(depEvents)# and +#[code]handler::khr_prefetch_host(ptr, numBytes)#. + +_Returns_: An event which represents the command which is submitted to the +queue. + +''' + +[[sec:khr-prefetch-host-example]] +== Example + +The example below demonstrates the usage of this extension. + +[source,,linenums] +---- +#include + +int main() { + sycl::queue Q; + int *A = Q.malloc_shared(1,Q); + Q.prefetch_host(sizeof(int)).wait(); + A[0] = 10; // Maybe faster than without the prefetch_host +} +---- From cdc9682eb451d361fd7e53ba70aab45b78e6794d Mon Sep 17 00:00:00 2001 From: tapplencourt Date: Thu, 12 Feb 2026 23:13:39 +0000 Subject: [PATCH 2/6] Fix naming and section --- adoc/extensions/sycl_khr_prefetch_host.adoc | 41 +++++---------------- 1 file changed, 9 insertions(+), 32 deletions(-) diff --git a/adoc/extensions/sycl_khr_prefetch_host.adoc b/adoc/extensions/sycl_khr_prefetch_host.adoc index d6e746713..ad2d96359 100644 --- a/adoc/extensions/sycl_khr_prefetch_host.adoc +++ b/adoc/extensions/sycl_khr_prefetch_host.adoc @@ -23,40 +23,12 @@ An implementation supporting this extension must predefine the macro |Initial version of this extension. |=== -[[sec:khr-prefetch-host-queue]] -== Extensions to the queue class +[[sec:khr-prefetch-host-handle]] +== Extensions to the handle class This extension adds the following function to the [code]#sycl::handler# class. -''' - -[source,role=synopsis,id=api:khr-prefetch-host-queue] ----- -namespace sycl { -class handler { - void khr_prefetch_host(); - // ... -}; -} ----- - -This extension adds the following function to the [code]#sycl::queue# class. - -''' - -[source,role=synopsis,id=api:khr-prefetch-host-queue] ----- -namespace sycl { -class queue { - event khr_prefetch_host(void* ptr, size_t numBytes); - event khr_prefetch_host(void* ptr, size_t numBytes, event depEvent); - event khr_prefetch_host(void* ptr, size_t numBytes, const std::vector& depEvents); - // ... -}; -} ----- - -[[sec:khr-prefetch-host-handle-menber-funcs]] +[[sec:khr-prefetch-host-handle-member-funcs]] === Member functions .[apidef]#handle::khr_prefetch_host# @@ -74,7 +46,12 @@ effect the functional behavior of the SYCL kernel function. ''' -[[sec:khr-prefetch-host-queue-menber-funcs]] +[[sec:khr-prefetch-host-queue]] +== Extensions to the queue class + +This extension adds the following function to the [code]#sycl::queue# class. + +[[sec:khr-prefetch-host-queue-member-funcs]] === Member functions .[apidef]#queue::khr_prefetch_host# From a8a9a2c507bb4a90c1ff25440a20f63b59131776 Mon Sep 17 00:00:00 2001 From: tapplencourt Date: Thu, 12 Feb 2026 23:21:20 +0000 Subject: [PATCH 3/6] fix code asci doc --- adoc/extensions/sycl_khr_prefetch_host.adoc | 30 ++++++++++----------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/adoc/extensions/sycl_khr_prefetch_host.adoc b/adoc/extensions/sycl_khr_prefetch_host.adoc index ad2d96359..7c413020c 100644 --- a/adoc/extensions/sycl_khr_prefetch_host.adoc +++ b/adoc/extensions/sycl_khr_prefetch_host.adoc @@ -23,22 +23,22 @@ An implementation supporting this extension must predefine the macro |Initial version of this extension. |=== -[[sec:khr-prefetch-host-handle]] -== Extensions to the handle class +[[sec:khr-prefetch-host-handler]] +== Extensions to the handler class This extension adds the following function to the [code]#sycl::handler# class. -[[sec:khr-prefetch-host-handle-member-funcs]] +[[sec:khr-prefetch-host-handler-member-funcs]] === Member functions -.[apidef]#handle::khr_prefetch_host# -[source,role=synopsis,id=api:handle-khr-prefetch-host] +.[apidef]#handler::khr_prefetch_host# +[source,role=synopsis,id=api:handler-khr-prefetch-host] ---- void khr_prefetch_host(void* ptr, size_t numBytes) ---- -_Effects:_ Prefetches a number of elements specified by #[code]numElements# into -the host memory cache +_Effects:_ Prefetches a number of elements specified by [code]#numElements# into +the host memory cache. {note} This operation is an implementation-defined optimization and does not effect the functional behavior of the SYCL kernel function. @@ -65,16 +65,16 @@ event khr_prefetch_host(void* ptr, size_t numBytes, const std::vector& de ---- -_Effects (1)_: Equivalent to calling #[code]queue::submit# with a command group -function that calls #[code]handler::khr_prefetch_host(ptr, numBytes)#. +_Effects (1)_: Equivalent to calling [code]#queue::submit# with a command group +function that calls [code]#handler::khr_prefetch_host(ptr, numBytes)#. -_Effects (2)_: Equivalent to calling #[code]queue::submit# with a command group -function that calls #[code]handler::depends_on(depEvent)# and -#[code]handler::khr_prefetch_host(ptr, numBytes)#. +_Effects (2)_: Equivalent to calling [code]#queue::submit# with a command group +function that calls [code]#handler::depends_on(depEvent)# and +[code]#handler::khr_prefetch_host(ptr, numBytes)#. -_Effects (3)_: Equivalent to calling #[code]queue::submit# with a command group -function that calls #[code]handler::depends_on(depEvents)# and -#[code]handler::khr_prefetch_host(ptr, numBytes)#. +_Effects (3)_: Equivalent to calling [code]#queue::submit# with a command group +function that calls [code]#handler::depends_on(depEvents)# and +[code]#handler::khr_prefetch_host(ptr, numBytes)#. _Returns_: An event which represents the command which is submitted to the queue. From 39dad704be58dfaff08998bec847c59a42bdca2e Mon Sep 17 00:00:00 2001 From: tapplencourt Date: Thu, 12 Feb 2026 23:25:42 +0000 Subject: [PATCH 4/6] Fix code example --- adoc/extensions/sycl_khr_prefetch_host.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adoc/extensions/sycl_khr_prefetch_host.adoc b/adoc/extensions/sycl_khr_prefetch_host.adoc index 7c413020c..a0fbfb88d 100644 --- a/adoc/extensions/sycl_khr_prefetch_host.adoc +++ b/adoc/extensions/sycl_khr_prefetch_host.adoc @@ -93,7 +93,7 @@ The example below demonstrates the usage of this extension. int main() { sycl::queue Q; int *A = Q.malloc_shared(1,Q); - Q.prefetch_host(sizeof(int)).wait(); + Q.prefetch_host(A, sizeof(int)).wait(); A[0] = 10; // Maybe faster than without the prefetch_host } ---- From 4ddf0dd56109b9b6cb4da3b823daa41d0325e53e Mon Sep 17 00:00:00 2001 From: tapplencourt Date: Thu, 12 Feb 2026 23:35:50 +0000 Subject: [PATCH 5/6] fix description --- adoc/extensions/sycl_khr_prefetch_host.adoc | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/adoc/extensions/sycl_khr_prefetch_host.adoc b/adoc/extensions/sycl_khr_prefetch_host.adoc index a0fbfb88d..04209a11b 100644 --- a/adoc/extensions/sycl_khr_prefetch_host.adoc +++ b/adoc/extensions/sycl_khr_prefetch_host.adoc @@ -37,11 +37,14 @@ This extension adds the following function to the [code]#sycl::handler# class. void khr_prefetch_host(void* ptr, size_t numBytes) ---- -_Effects:_ Prefetches a number of elements specified by [code]#numElements# into -the host memory cache. - -{note} This operation is an implementation-defined optimization and does not -effect the functional behavior of the SYCL kernel function. +_Effects:_ Enqueues a prefetch host of [code]#num_bytes# of data starting at address +[code]#ptr#. The [code]#ptr# must point within a USM allocation from the same +context as the handler's queue, and the pointer must be accessible from the +queue's device. For more detail on USM, please see <>. + +{note} [code]#prefetch_host# inform the SYCL runtime that the specified shared allocation is +likely to be accessed on the host in the future, and that it is free +to migrate the allocation to the host. {endnote} ''' From 9df00a76b5030b615df114c33fd6ad1abbabce6c Mon Sep 17 00:00:00 2001 From: tapplencourt Date: Thu, 12 Feb 2026 23:41:15 +0000 Subject: [PATCH 6/6] Run reflow --- adoc/extensions/sycl_khr_prefetch_host.adoc | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/adoc/extensions/sycl_khr_prefetch_host.adoc b/adoc/extensions/sycl_khr_prefetch_host.adoc index 04209a11b..4fe50ddd1 100644 --- a/adoc/extensions/sycl_khr_prefetch_host.adoc +++ b/adoc/extensions/sycl_khr_prefetch_host.adoc @@ -37,14 +37,15 @@ This extension adds the following function to the [code]#sycl::handler# class. void khr_prefetch_host(void* ptr, size_t numBytes) ---- -_Effects:_ Enqueues a prefetch host of [code]#num_bytes# of data starting at address -[code]#ptr#. The [code]#ptr# must point within a USM allocation from the same -context as the handler's queue, and the pointer must be accessible from the -queue's device. For more detail on USM, please see <>. - -{note} [code]#prefetch_host# inform the SYCL runtime that the specified shared allocation is -likely to be accessed on the host in the future, and that it is free -to migrate the allocation to the host. +_Effects:_ Enqueues a prefetch host of [code]#num_bytes# of data starting at +address [code]#ptr#. +The [code]#ptr# must point within a USM allocation from the same context as the +handler's queue, and the pointer must be accessible from the queue's device. +For more detail on USM, please see <>. + +{note} [code]#prefetch_host# inform the SYCL runtime that the specified shared +allocation is likely to be accessed on the host in the future, and that it is +free to migrate the allocation to the host. {endnote} '''