Skip to content

Commit 882a371

Browse files
lapel22lapel22
authored
[SYCLomatic][DOC] 2025.1 Migration Examples (#2698)
1 parent c2f7980 commit 882a371

File tree

2 files changed

+178
-0
lines changed

2 files changed

+178
-0
lines changed

‎docs/dev_guide/reference.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ mapping CUDA* concepts and APIs to SYCL*.
1515
reference/dpct-namespace-reference
1616
reference/compare-prog-models
1717
reference/term-mapping-quick-ref
18+
reference/migration-examples
1819

1920

2021

‎docs/dev_guide/reference/migration-examples.rst

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
.. _migration_examples:
2+
3+
Migration Examples
4+
==================
5+
6+
External Memory Interoperability
7+
--------------------------------
8+
9+
|tool_name| now supports experimental migration of DirectX (11/12) and
10+
Vulkan Interoperability with CUDA using option
11+
``--use-experimental-features=bindless_images``.
12+
13+
Supported CUDA APIs
14+
*******************
15+
* **cudaGraphicsMapResources**
16+
* **cudaGraphicsResourceGetMappedPointer**
17+
* **cudaGraphicsSubResourceGetMappedArray**
18+
* **cudaGraphicsResourceGetMappedMipmappedArray**
19+
* **cudaGraphicsUnmapResources**
20+
* **cudaGraphicsUnregisterResource**
21+
* **cudaGraphicsResourceSetMapFlags**
22+
* **cudaGraphicsD3D11RegisterResource**
23+
* **cudaDestroyExternalMemory**
24+
* **CudaExternalMemoryGetMappedBuffer**
25+
* **cudaExternalMemoryGetMappedMipmappedArray**
26+
* **cudaImportExternalMemory**
27+
28+
Examples
29+
********
30+
31+
DirectX-CUDA Interoperability
32+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
33+
34+
CUDA
35+
36+
.. code-block:: none
37+
38+
// Create a resource using DirectX APIs
39+
ID3D11Resource *d3dResource
40+
41+
cudaGraphicsResource_t cudaResource;
42+
43+
// Register the DirectX resource with CUDA
44+
cudaGraphicsD3D11RegisterResource(&cudaResource, d3dResource,
45+
cudaGraphicsRegisterFlagsNone);
46+
47+
// Set the flags for CUDA resource mapping
48+
cudaGraphicsResourceSetMapFlags(cudaResource, cudaGraphicsMapFlagsNone);
49+
50+
// Map the CUDA resource for access
51+
cudaGraphicsMapResources(1, &cudaResource);
52+
53+
// Get the mapped array from the CUDA resource
54+
cudaArray_t cudaArr;
55+
cudaGraphicsSubResourceGetMappedArray(&cudaArr, cudaResource, 0, 0);
56+
57+
// Unmap the CUDA resource
58+
cudaGraphicsUnmapResources(1, &cudaResource);
59+
60+
// Unregister the CUDA resource
61+
cudaGraphicsUnregisterResource(cudaResource);
62+
63+
Migrated Code
64+
65+
.. code-block:: none
66+
67+
// Create a resource using DirectX APIs
68+
ID3D11Resource *d3dResource
69+
70+
dpct::experimental::external_mem_wrapper_ptr cudaResource;
71+
72+
// Register the DirectX resource with CUDA
73+
cudaResource = new dpct::experimental::external_mem_wrapper(d3dResource,
74+
0);
75+
76+
// Set the flags for CUDA resource mapping
77+
/*
78+
DPCT1026:1: The call to cudaGraphicsResourceSetMapFlags was removed because this functionality is deprecated in DX12 and hence is not supported in SYCL.
79+
*/
80+
81+
// Map the CUDA resource for access
82+
dpct::experimental::map_resources(1, &cudaResource);
83+
84+
// Get the mapped array from the CUDA resource
85+
dpct::experimental::image_mem_wrapper_ptr cudaArr;
86+
cudaArr = cudaResource->get_sub_resource_mapped_array(0, 0);
87+
88+
// Unmap the CUDA resource
89+
dpct::experimental::unmap_resources(1, &cudaResource);
90+
91+
// Unregister the CUDA resource
92+
delete cudaResource;
93+
94+
Vulkan-CUDA Interoperability
95+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
96+
97+
CUDA
98+
99+
.. code-block:: none
100+
101+
// Create a resource using Vulkan APIs
102+
VkImage vkTexture;
103+
104+
cudaExternalMemoryHandleDesc memHandleDesc; cudaExternalMemoryMipmappedArrayDesc mipmapDesc;
105+
cudaExternalMemory_t externalMemory;
106+
107+
// Import the memory from external resource (Vulkan)
108+
cudaImportExternalMemory(&externalMemory, &memHandleDesc);
109+
110+
// Get the mapped array from the CUDA resource
111+
cudaMipmappedArray_t cudaMipmappedArray = nullptr;
112+
cudaExternalMemoryGetMappedMipmappedArray(&cudaMipmappedArray,
113+
externalMemory,
114+
&mipmapDesc);
115+
116+
// Retrieve the tex data as a cudaArray from cudaMipmappedArray
117+
cudaArray_t cudaArr;
118+
cudaGetMipmappedArrayLevel(&cudaArr, cudaMipmappedArray, 0);
119+
120+
// Destroy the CUDA resource
121+
cudaDestroyExternalMemory(externalMemory);
122+
123+
Migrated Code
124+
125+
.. code-block:: none
126+
127+
// Create a resource using Vulkan APIs
128+
VkImage vkTexture;
129+
130+
dpct::experimental::external_mem_handle_desc memHandleDesc;
131+
dpct::experimental::external_mem_img_desc mipmapDesc;
132+
sycl::ext::oneapi::experimental::external_mem externalMemory;
133+
134+
// Import the memory from external resource (Vulkan)
135+
dpct::experimental::import_external_memory(&externalMemory, &memHandleDesc));
136+
137+
// Get the mapped array from the CUDA resource
138+
dpct::experimental::image_mem_wrapper_ptr cudaMipmappedArray = nullptr;
139+
cudaMipmappedArray = new dpct::experimental::image_mem_wrapper(
140+
externalMemory,
141+
&mipmapDesc);
142+
143+
// Retrieve the tex data as a cudaArray from cudaMipmappedArray
144+
dpct::experimental::image_mem_wrapper_ptr cudaArr;
145+
cudaArr = cudaMipmappedArray->get_mip_level(0);
146+
147+
// Destroy the CUDA resource
148+
sycl::ext::oneapi::experimental::release_external_memory(
149+
externalMemory, dpct::get_in_order_queue());
150+
151+
Additional Migration Examples
152+
-----------------------------
153+
154+
Example: Migrate QuickSilver to SYCL Version
155+
********************************************
156+
157+
View a `list of detailed steps <https://github.com/oneapi-src/SYCLomatic-test/tree/SYCLomatic/third-party-programs/Velocity-Bench/QuickSilver>`__ to migrate CUDA version of
158+
QuickSilver to SYCL version.
159+
160+
Example: Migrate cudaSift to SYCL Version
161+
*****************************************
162+
163+
View a `list of detailed steps <https://github.com/oneapi-src/SYCLomatic-test/tree/SYCLomatic/third-party-programs/Velocity-Bench/cudaSift>`__ to migrate CUDA version
164+
of cudaSift to SYCL version.
165+
166+
Example: Migrate hplinpack to SYCL Version
167+
******************************************
168+
169+
View a `list of detailed steps <https://github.com/oneapi-src/SYCLomatic-test/tree/SYCLomatic/third-party-programs/Velocity-Bench/hplinpack>`__ to migrate CUDA version
170+
of hplinpack to SYCL version.
171+
172+
Example: Migrate bitcracker to SYCL Version
173+
*******************************************
174+
175+
View a `list of detailed steps <https://github.com/oneapi-src/SYCLomatic-test/tree/SYCLomatic/third-party-programs/Velocity-Bench/bitcracker>`__ to migrate CUDA version
176+
of bitcracker to SYCL version.
177+

0 commit comments

Comments
 (0)