You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Vector Add is the equivalent of a ‘Hello, World!’ sample for data parallel
4
-
programs. Building and running the code sample verifies that your development
5
-
environment is set up correctly and demonstrates the use of the core features of
6
-
SYCL*.
3
+
The `Base: Vector Add` is the equivalent of a ‘Hello, World!’ sample for data parallel programs. Building and running this sample verifies that your development environment is set up correctly, and the sample code demonstrates some core features of SYCL*.
7
4
8
-
For comprehensive instructions, see the [Intel® oneAPI Programming
9
-
Guide](https://software.intel.com/en-us/oneapi-programming-guide) and search
10
-
based on relevant terms noted in the comments.
11
-
12
-
13
-
| Optimized for | Description
14
-
|:--- |:---
15
-
| OS | Linux* Ubuntu* 18.04 <br>Windows* 10
16
-
| Hardware | Skylake with GEN9 or newer <br>Intel® Programmable Acceleration Card with Intel® Arria® 10 GX FPGA
17
-
| Software | Intel® oneAPI DPC++/C++ Compiler
5
+
| Area | Description
6
+
|:--- |:---
7
+
| What you will learn | How to begin using SYCL* to offload computations to a GPU
8
+
| Time to complete | 15 minutes
18
9
19
10
## Purpose
11
+
The `Base: Vector Add` is a simple program that adds two large vectors of integers and verifies the results. This program uses C++ and SYCL* for Intel® CPU and accelerators.
20
12
21
-
The `vector-add` is a simple program that adds two large vectors of integers and
22
-
verifies the results. This program is implemented using C++ and SYCL* for
23
-
Intel® CPU and accelerators.
24
-
25
-
In this sample, you can learn how to use the most basic code in C++ language
26
-
that offloads computations to a GPU. This includes using Unified Shared Memory
27
-
(USM) and buffers. USM requires an explicit wait for the asynchronous kernel's
28
-
computation to complete. Buffers, at the time they go out of scope, bring main
29
-
memory in sync with device memory implicitly; the explicit wait on the event is
30
-
not required as a result. This sample provides examples of both implementations
31
-
for simple side-by-side reviews (the Windows sample only supports USM).
32
-
33
-
The code attempts to execute on an available GPU and fallback to the system CPU
34
-
if a compatible GPU is not detected. If successful, the name of the offload
35
-
device and a success message is displayed, which indicates your development
36
-
environment is set up correctly.
37
-
38
-
In addition, you can target an FPGA device using the build scripts described
39
-
below. If you do not have FPGA hardware, the sample will run in emulation mode,
40
-
which includes static optimization reports for design analysis.
13
+
In this sample, you can learn how to use C++ code to offload computations to a GPU. This includes using Unified Shared Memory (USM) and buffers. USM requires an explicit wait for the asynchronous kernel's computation to complete. Buffers, at the time they go out of scope, bring main memory in sync with device memory implicitly; the explicit wait on the event is not required as a result. This sample provides examples of both implementations for simple side-by-side reviews (the Windows sample only supports USM).
41
14
42
15
A detailed code walkthrough can be found in the [Explore SYCL* with Samples from
> **Note**: For comprehensive information about oneAPI programming, see the [Intel® oneAPI Programming Guide](https://software.intel.com/en-us/oneapi-programming-guide). (Use search or the table of contents to find relevant information quickly.)
20
+
21
+
## Prerequisites
22
+
| Optimized for | Description
23
+
|:--- |:---
24
+
| OS | Ubuntu* 18.04 <br> Windows* 10
25
+
| Hardware | Skylake with GEN9 or newer <br>Intel® Programmable Acceleration Card with Intel® Arria® 10 GX FPGA
26
+
| Software | Intel® oneAPI DPC++/C++ Compiler
27
+
46
28
## Key Implementation Details
29
+
The basic SYCL* implementation explained in the code includes device selector, USM, buffer, accessor, kernel, and command groups.
47
30
48
-
The basic SYCL* implementation explained in the code includes device selector,
49
-
USM, buffer, accessor, kernel, and command groups.
31
+
The code attempts to execute on an available GPU and fallback to the system CPU if a compatible GPU is not detected. If successful, the name of the offload device and a success message is displayed, which indicates your development environment is set up correctly.
50
32
51
-
## License
52
-
Code samples are licensed under the MIT license. See
In addition, you can target an FPGA device using the build scripts described below. If you do not have FPGA hardware, the sample will run in emulation mode, which includes static optimization reports for design analysis.
With oneAPI 2021.4 the argument for accessors was changed from `noinit` to `no_init`. The change was derived from a change between the SYCL 2020
37
+
provisional spec and that of the 2020Rev3 spec.
58
38
59
-
## Known Issues
60
-
With oneAPI 2021.4 the argument for accessors was changed from `noinit` to
61
-
`no_init`. The change was derived from a change between the SYCL 2020
62
-
provisional spec and that of the 2020Rev3 spec
39
+
If this sample fails to run, do one of the following:
40
+
- Update the Intel® oneAPI Base Toolkit to 2021.4 or later.
41
+
- Change the `no_init` argument to `noinit`.
63
42
64
-
If running this sample and it fails, do one of the following
65
-
- Update the Intel® oneAPI Base Toolkit to 2021.4
66
-
- Change the 'no_init' argument to 'noinit'
43
+
## Setting Environment Variables
44
+
When working with the command-line interface (CLI), you should configure the oneAPI toolkits using environment variables. Set up your CLI environment by sourcing the `setvars` script every time you open a new terminal window. This practice ensures that your compiler, libraries, and tools are ready for development.
67
45
68
-
> **Note**: If you have not already done so, set up your CLI environment by
69
-
> sourcing the `setvars` script located in the root of your oneAPI
70
-
> installation.
46
+
## Build the `Base: Vector Add` Sample for GPU and FPGA
47
+
> **Note**: If you have not already done so, set up your CLI
48
+
> environment by sourcing the `setvars` script in the root of your oneAPI installation.
71
49
>
72
-
> Linux:
50
+
> Linux*:
73
51
> - For system wide installations: `. /opt/intel/oneapi/setvars.sh`
74
52
> - For private installations: `. ~/intel/oneapi/setvars.sh`
53
+
> - For non-POSIX shells, like csh, use the following command: `bash -c 'source <install-dir>/setvars.sh ; exec csh'`
> For more information on configuring environment variables, see [Use the setvars Script with Linux* or macOS*](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-linux-or-macos.html) or [Use the setvars Script with Windows*](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-windows.html).
84
60
85
-
### Running Samples in DevCloud
86
-
87
-
If running a sample in the Intel DevCloud, you must specify the compute node
88
-
(CPU, GPU, FPGA) and whether to run in batch or interactive mode. For more
89
-
information, see the Intel® oneAPI Base Toolkit [Get Started
1. Configure the oneAPI environment with the extension **Environment Configurator for Intel® oneAPI Toolkits**.
67
+
2. Download a sample using the extension **Code Sample Browser for Intel® oneAPI Toolkits**.
68
+
3. Open a terminal in VS Code (**Terminal > New Terminal**).
69
+
4. Run the sample in the VS Code terminal using the instructions below.
108
70
109
-
After learning how to use the extensions for Intel®oneAPI Toolkits, return
110
-
to this readme for instructions on how to build and run a sample.
71
+
To learn more about the extensions and how to configure the oneAPI environment, see the
72
+
[Using Visual Studio Code with Intel® oneAPI Toolkits User Guide](https://www.intel.com/content/www/us/en/develop/documentation/using-vs-code-with-intel-oneapi/top.html).
111
73
112
-
113
-
### On Linux* using the Command Line
114
-
Perform the following steps:
115
-
116
-
1. Build the program using the following `make` commands (default uses buffers):
74
+
### On Linux* for CPU and GPU
75
+
1. Build the program.
117
76
```
118
-
make all
77
+
make build_usm
119
78
```
120
-
> **Note**: For USM use `make build_usm`
79
+
> **Note**: To build everything, use `make all`.
121
80
122
-
2. Run the program using:
81
+
### On Linux* for FPGA
82
+
1. Build for FPGA emulation using the following commands:
123
83
```
124
-
make run
84
+
make fpga_emu -f Makefile.fpga
125
85
```
126
-
> **Note**: For USM use `make run_usm`
127
-
128
-
3. Clean the program using:
86
+
2. Build for FPGA hardware. (Compiling for hardware can take a long
2. Build the program using the following `nmake` commands:
91
+
3. Generate static optimization reports for design analysis. (The path to the
92
+
reports is `vector-add_report.prj/reports/report.html`.)
138
93
```
139
-
nmake -f Makefile.win
94
+
make report -f Makefile.fpga
140
95
```
141
-
> **Note**: For USM use `nmake -f Makefile.win build_usm`
142
-
143
-
3. Run the program using:
96
+
### On Windows* for CPU and GPU
97
+
1. Open the **Intel oneAPI Command Prompt**.
98
+
2. Build the program.
144
99
```
145
-
nmake -f Makefile.win run
100
+
nmake -f Makefile.win build_usm
146
101
```
147
-
> **Note**: For USM use `nmake -f Makefile.win run_usm`
102
+
> **Note**: To build everything, use `nmake -f Makefile.win`
148
103
149
-
4. Clean the program using:
150
-
```
151
-
nmake -f Makefile.win clean
152
-
```
104
+
### On Windows for FPGA Emulation Only
105
+
> **Note** On Windows*, you can compile and run on the FPGA
106
+
emulator only. Generating optimization reports and compiling or running on
107
+
the FPGA hardware is not supported.
153
108
154
-
### On a Windows* System Using Visual Studio* Version 2017 or Newer
155
-
Perform the following steps:
156
-
1. Launch the Visual Studio* 2017.
157
-
2. Select the menu sequence **File** > **Open** > **Project/Solution**.
158
-
3. Locate the `vector-add` folder.
109
+
1. Open the **Intel oneAPI Command Prompt**.
110
+
111
+
2. Build the program.
112
+
```
113
+
nmake -f Makefile.win.fpga
114
+
```
115
+
### On Windows Using Visual Studio* 2017 or Newer
116
+
1. Change to the sample directory.
117
+
2. Launch Visual Studio*.
118
+
3. Select the menu sequence **File** > **Open** > **Project/Solution**.
159
119
4. Select the `vector-add.sln` file.
160
-
5. Select the configuration 'Debug' or 'Release'
161
-
6. Select **Project** > **Build** menu option to build the selected
162
-
configuration.
163
-
7. Select **Debug** > **Start Without Debugging** menu option to run the
164
-
program.
120
+
5. For CPU and GPU, skip to Step 7 (below).
121
+
6. For FPGA emulation only, select the configuration **Debug-fpga**, which contains the settings shown in below. Alternatively, confirm the following settings from the **Project Property** dialog.
122
+
123
+
a. Select the **DPC++** tab.
124
+
125
+
b. **General** > **Perform ahead of time compilation for the FPGA** is set to **Yes**.
165
126
166
-
## Building the `vector-add` Program for Intel® FPGA
127
+
c. **Preprocessor** > **Preprocessor Definitions** contains **FPGA_EMULATOR=1**.
167
128
168
-
### Linux*
129
+
7. Select **Project** > **Build** menu option to build the selected
130
+
configuration.
131
+
8. Select **Debug** > **Start Without Debugging** menu option to run the
132
+
program.
169
133
170
-
Perform the following steps:
134
+
#### Troubleshooting
135
+
If you receive an error message, troubleshoot the problem using the **Diagnostics Utility for Intel® oneAPI Toolkits**. The diagnostic utility provides configuration and system checks to help find missing dependencies, permissions errors, and other issues. See the [Diagnostics Utility for Intel® oneAPI Toolkits User Guide](https://www.intel.com/content/www/us/en/develop/documentation/diagnostic-utility-user-guide/top.html) for more information on using the utility.
171
136
172
-
1. Clean the `vector-add` program using:
137
+
## Run the Sample
138
+
### On Linux for CPU and GPU
139
+
1. Run the program.
173
140
```
174
-
make clean -f Makefile.fpga
141
+
make run_usm
175
142
```
176
-
2. Based on your requirements, you can perform the following:
177
-
* Build and run for FPGA emulation using the following commands:
143
+
> **Note**: To run everything, use `make run`.
144
+
145
+
### On Linux for FPGA
146
+
1. Run for FPGA emulation.
178
147
```
179
-
make fpga_emu -f Makefile.fpga
180
148
make run_emu -f Makefile.fpga
181
149
```
182
-
* Build and run for FPGA hardware. (The hardware compilation can take a long
183
-
time to complete.)
150
+
2. Run on FPGA hardware.
184
151
```
185
-
make hw -f Makefile.fpga
186
152
make run_hw -f Makefile.fpga
187
153
```
188
-
* Generate static optimization reports for design analysis. Path to the
189
-
reports is `vector-add_report.prj/reports/report.html`
154
+
### On Windows for CPU and GPU
155
+
1. Open the **Intel oneAPI Command Prompt**.
156
+
3. Run the program using:
190
157
```
191
-
make report -f Makefile.fpga
158
+
nmake -f Makefile.win run_usm
192
159
```
160
+
> **Note**: To run everything, use `nmake -f Makefile.win run`
193
161
194
-
### On Windows Using a Command Line Interface
195
-
Perform the following steps:
196
-
197
-
> **Note** On a Windows* system, you can only compile and run on the FPGA
198
-
emulator. Generating an HTML optimization report and compiling and running on
2. Build the program using the following `nmake` commands:
162
+
## On Windows for FPGA Emulation
163
+
1. Open the **Intel oneAPI Command Prompt**.
164
+
2. Build the program.
204
165
```
205
-
nmake -f Makefile.win.fpga clean
206
-
nmake -f Makefile.win.fpga
207
166
nmake -f Makefile.win.fpga run
208
167
```
168
+
### Run the `Base: Vector Add` Sample in Intel® DevCloud (Optional)
169
+
When running a sample in the Intel® DevCloud, you must specify the compute node (CPU, GPU, FPGA) and whether to run in batch or interactive mode. For more information, see the Intel® oneAPI Base Toolkit [Get Started Guide](https://devcloud.intel.com/oneapi/get_started/).
209
170
210
-
### On Windows Using Visual Studio* Version 2017 or Newer
211
-
Perform the following steps:
212
-
1. Launch the Visual Studio* 2017.
213
-
2. Select the menu sequence **File** > **Open** > **Project/Solution**.
214
-
3. Locate the `vector-add` folder.
215
-
4. Select the `vector-add.sln` file.
216
-
5. Select the configuration 'Debug-fpga' that have the necessary project
217
-
settings already below:
218
-
219
-
Under the 'Project Property' dialog:
220
-
221
-
a. Select the **DPC++** tab. <br>b. In the **General** subtab, the
222
-
**Perform ahead of time compilation for the FPGA** setting is set to
223
-
**Yes**. <br>c. In the **Preprocessor** subtab, the **Preprocessor
224
-
Definitions" setting has **FPGA_EMULATOR=1** added. <br>d. Close the
225
-
dialog.
226
-
227
-
6. Select **Project** > **Build** menu option to build the selected
228
-
configuration.
229
-
7. Select **Debug** > **Start Without Debugging** menu option to run the
230
-
program.
231
-
232
-
## Running the Sample
233
171
### Application Parameters
234
-
There is an optional parameter which determines the size of vector. Default
235
-
value is 10000.
172
+
There is an optional parameter which determines vector size. Default value is `10000`.
236
173
237
-
### Example of Output
174
+
## Example Output
238
175
```
239
176
Running on device: Intel(R) Gen(R) HD Graphics NEO
240
177
Vector size: 10000
@@ -246,9 +183,10 @@ Vector size: 10000
246
183
Vector add successfully completed on device.
247
184
```
248
185
249
-
## Troubleshooting
250
-
If you receive an error message, troubleshoot the problem using the Diagnostics
251
-
Utility for Intel® oneAPI Toolkits, which provides system checks to find
252
-
missing dependencies and permissions errors. See [Diagnostics Utility for
0 commit comments