Name	Name	Last commit message	Last commit date
parent directory ..
src	src
CMakeLists.txt	CMakeLists.txt
README.md	README.md
sample.json	sample.json

`Stall Enable` Sample

This sample is an FPGA tutorial that demonstrates how to use the use_stall_enable_clusters attribute to reduce the area and computation latency of your FPGA kernels. This attribute may reduce the FPGA FMax for your kernels.

Area	Description
What you will learn	What the `use_stall_enable_clusters` attribute does. How `use_stall_enable_clusters` attribute affects resource usage and latency. How to apply the `use_stall_enable_clusters` attribute to kernels in your program.
Time to complete	15 minutes (emulator and report) several hours (fpga bitstream generation)
Category	Concepts and Functionality

Purpose

The use_stall_enable_clusters attribute enables you to direct the compiler to reduce the area and latency of your kernel. Reducing the latency will not have a large effect on loops that are pipelined, unless the number of iterations of the loop is very small. Computations in an FPGA kernel are normally grouped into Stall Free Clusters. This allows simplification of the signals within the cluster, but there is a FIFO queue at the end of the cluster that is used to save intermediate results if the computation needs to stall. Stall Enable Clusters save area and cycles by removing the FIFO queue and passing the stall signals to each part of the computation. These extra signals may cause the FMax to be reduced.

Note: If you specify [[intel::use_stall_enable_clusters]] on one or more kernels, this may reduce the FMax of the generated FPGA bitstream, which may reduce performance on all kernels.

Note: The use_stall_enable_clusters attribute is not applicable for designs that target FPGA architectures that support hyper optimized handshaking, unless the -Xshyper-optimized-handshaking=off argument is passed to icpx.

Prerequisites

Optimized for	Description
OS	Ubuntu* 20.04 RHEL/CentOS 8 SUSE* 15 Windows* 10, 11 Windows Server* 2019
Hardware	Intel® Agilex® 7, Agilex® 5, Arria® 10, Stratix® 10, and Cyclone® V FPGAs
Software	Intel® oneAPI DPC++/C++ Compiler

Note: Even though the Intel DPC++/C++ oneAPI compiler is enough to compile for emulation, generating reports and generating RTL, there are extra software requirements for the simulation flow and FPGA compiles.

For using the simulator flow, Intel® Quartus® Prime Pro Edition (or Standard Edition when targeting Cyclone® V) and one of the following simulators must be installed and accessible through your PATH:

Questa*-Intel® FPGA Edition

Questa*-Intel® FPGA Starter Edition

ModelSim® SE

When using the hardware compile flow, Intel® Quartus® Prime Pro Edition (or Standard Edition when targeting Cyclone® V) must be installed and accessible through your PATH.

Warning: Make sure you add the device files associated with the FPGA that you are targeting to your Intel® Quartus® Prime installation.

This sample is part of the FPGA code samples. It is categorized as a Tier 3 sample that demonstrates a compiler feature.

flowchart LR
   tier1("Tier 1: Get Started")
   tier2("Tier 2: Explore the Fundamentals")
   tier3("Tier 3: Explore the Advanced Techniques")
   tier4("Tier 4: Explore the Reference Designs")

   tier1 --> tier2 --> tier3 --> tier4

   style tier1 fill:#0071c1,stroke:#0071c1,stroke-width:1px,color:#fff
   style tier2 fill:#0071c1,stroke:#0071c1,stroke-width:1px,color:#fff
   style tier3 fill:#f96,stroke:#333,stroke-width:1px,color:#fff
   style tier4 fill:#0071c1,stroke:#0071c1,stroke-width:1px,color:#fff

Find more information about how to navigate this part of the code samples in the FPGA top-level README.md. You can also find more information about troubleshooting build errors, links to selected documentation, and more.

Key Implementation Details

The sample illustrates the following important concepts.

Description of the use_stall_enable_clusters attribute
How use_stall_enable_clusters attribute affects resource usage and loop throughput
How to apply the use_stall_enable_clusters attribute to kernels in your program

Example of Using the `use_stall_enable_clusters` Attribute

h.single_task<class KernelComputeStallFree>( [=]() [[intel::use_stall_enable_clusters]] {
  // The computations in this device kernel will use Stall Enable clusters
  Work(accessor_vec_a, accessor_vec_b, accessor_res);
});

The FPGA compiler will use Stall Enable Clusters for the kernel when possible. Some computations may not be able to stall and need to be placed in a Stall Free Cluster.

Build the `Stall Enable` Tutorial

Note: 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 in the root of your oneAPI installation every time you open a new terminal window. This practice ensures that your compiler, libraries, and tools are ready for development.

Linux*:

For system wide installations: . /opt/intel/oneapi/setvars.sh

For private installations: . ~/intel/oneapi/setvars.sh

For non-POSIX shells, like csh, use the following command: bash -c 'source <install-dir>/setvars.sh ; exec csh'

Windows*:

C:\Program Files (x86)\Intel\oneAPI\setvars.bat

Windows PowerShell*, use the following command: cmd.exe "/K" '"C:\Program Files (x86)\Intel\oneAPI\setvars.bat" && powershell'

For more information on configuring environment variables, see Use the setvars Script with Linux* or macOS* or Use the setvars Script with Windows*.

On Linux*

Change to the sample directory.
Build the program for Intel® Agilex® 7 device family, which is the default.
```
mkdir build
cd build
cmake .. -DPART=<X>
```
where X is:
- STALL_ENABLE
- STALL_FREE
Note: You can change the default target by using the command:
```
cmake .. -DFPGA_DEVICE=<FPGA device family or FPGA part number>
```
Alternatively, you can target an explicit FPGA board variant and BSP by using the following command:
```
cmake .. -DFPGA_DEVICE=<board-support-package>:<board-variant>
```

Note: You can poll your system for available BSPs using the aoc -list-boards command. The board list that is printed out will be of the form
$> aoc -list-boards
Board list:
  <board-variant>
     Board Package: <path/to/board/package>/board-support-package
  <board-variant2>
     Board Package: <path/to/board/package>/board-support-package
You will only be able to run an executable on the FPGA if you specified a BSP.

Note: For targets that support hyper-optimized handshaking, you must disable the handshaking with -DNO_HYPER_OPTIMIZATION=true.

Compile the design. (The provided targets match the recommended development flow.)
1. Compile and run for emulation (fast compile time, targets emulates an FPGA device).
```
make fpga_emu
```
2. Generate the HTML optimization reports. (See Read the Reports below for information on finding and understanding the reports.)
```
make report
```
3. Compile for simulation (fast compile time, targets simulated FPGA device).
```
make fpga_sim
```
4. Compile and run on FPGA hardware (longer compile time, targets an FPGA device).
```
make fpga
```

On Windows*

Change to the sample directory.
Build the program for the Intel® Agilex® 7 device family, which is the default.
```
mkdir build
cd build
cmake -G "NMake Makefiles" .. -DPART=<X>
```
where X is:
- STALL_ENABLE
- STALL_FREE
Note: You can change the default target by using the command:
```
cmake -G "NMake Makefiles" .. -DFPGA_DEVICE=<FPGA device family or FPGA part number>
```
Alternatively, you can target an explicit FPGA board variant and BSP by using the following command:
```
cmake -G "NMake Makefiles" .. -DFPGA_DEVICE=<board-support-package>:<board-variant>
```

Note: You can poll your system for available BSPs using the aoc -list-boards command. The board list that is printed out will be of the form
$> aoc -list-boards
Board list:
  <board-variant>
     Board Package: <path/to/board/package>/board-support-package
  <board-variant2>
     Board Package: <path/to/board/package>/board-support-package
You will only be able to run an executable on the FPGA if you specified a BSP.

Note: For targets that support hyper-optimized handshaking, you must disable the handshaking with -DNO_HYPER_OPTIMIZATION=true.

Compile the design. (The provided targets match the recommended development flow.)
1. Compile for emulation (fast compile time, targets emulated FPGA device).
```
nmake fpga_emu
```
2. Generate the optimization report. (See Read the Reports below for information on finding and understanding the reports.)
```
nmake report
```
3. Compile for simulation (fast compile time, targets simulated FPGA device, reduced problem size).
```
nmake fpga_sim
```
4. Compile for FPGA hardware (longer compile time, targets FPGA device):
```
nmake fpga
```

Note: If you encounter any issues with long paths when compiling under Windows*, you may have to create your 'build' directory in a shorter path, for example c:\samples\build. You can then run cmake from that directory, and provide cmake with the full path to your sample directory, for example:
C:\samples\build> cmake -G "NMake Makefiles" C:\long\path\to\code\sample\CMakeLists.txt

Read the Reports

Locate report.html files in both versions of the build (-DPART=STALL_ENABLE and -DPART=STALL_FREE).

On the main report page, scroll down to the section titled Compile Estimated Kernel Resource Utilization Summary. Note that the estimated number of MLABs for KernelComputeStallEnable is smaller than that of KernelComputeStallFree. The reduction in MLABs is due to the elimination of the FIFO queue at the end of the cluster.

Run the `Stall Enable` Sample

On Linux

Run the sample on the FPGA emulator (the kernel executes on the CPU).
```
./stall_enable.fpga_emu
```

Run the sample on the FPGA simulator device.

CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=1 ./stall_enable.fpga_sim

Run the sample on the FPGA device (only if you ran cmake with -DFPGA_DEVICE=<board-support-package>:<board-variant>).
```
./stall_enable.fpga
```

On Windows

Run the sample on the FPGA emulator (the kernel executes on the CPU).
```
stall_enable.fpga_emu.exe
```

Run the sample on the FPGA simulator device.

set CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=1
stall_enable.fpga_sim.exe
set CL_CONTEXT_MPSIM_DEVICE_INTELFPGA=

Note: Hardware runs are not supported on Windows.

Example Output

Example Output for `stall_enable.fpga_emu` compiled with `-DPART=STALL_FREE`

Running on device: ofs_n6001 : Intel OFS Platform (ofs_ee00000)
Stall free Kernel -- kernel time : 12.8 microseconds
Throughput for kernel: 15625001KB/s
PASSED: The results are correct

Example Output for `stall_enable.fpga_emu` compiled with `-DPART=STALL_ENABLE`

Running on device: ofs_n6001 : Intel OFS Platform (ofs_ee00000)
Stall enable Kernel -- kernel time : 7.936 microseconds
Throughput for kernel: 25201614KB/s
PASSED: The results are correct

There should be no observable difference in results in the example. Only the area and latency differences are visible in the reports.

License

Code samples are licensed under the MIT license. See License.txt for details.

Third-party program Licenses can be found here: third-party-programs.txt.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

stall_enable

stall_enable

README.md

`Stall Enable` Sample

Purpose

Prerequisites

Key Implementation Details

Example of Using the `use_stall_enable_clusters` Attribute

Build the `Stall Enable` Tutorial

On Linux*

On Windows*

Read the Reports

Run the `Stall Enable` Sample

On Linux

On Windows

Example Output

Example Output for `stall_enable.fpga_emu` compiled with `-DPART=STALL_FREE`

Example Output for `stall_enable.fpga_emu` compiled with `-DPART=STALL_ENABLE`

License

Files

stall_enable

Directory actions

More options

Directory actions

More options

Latest commit

History

stall_enable

Folders and files

parent directory

README.md

Stall Enable Sample

Purpose

Prerequisites

Key Implementation Details

Example of Using the use_stall_enable_clusters Attribute

Build the Stall Enable Tutorial

On Linux*

On Windows*

Read the Reports

Run the Stall Enable Sample

On Linux

On Windows

Example Output

Example Output for stall_enable.fpga_emu compiled with -DPART=STALL_FREE

Example Output for stall_enable.fpga_emu compiled with -DPART=STALL_ENABLE

License

`Stall Enable` Sample

Example of Using the `use_stall_enable_clusters` Attribute

Build the `Stall Enable` Tutorial

Run the `Stall Enable` Sample

Example Output for `stall_enable.fpga_emu` compiled with `-DPART=STALL_FREE`

Example Output for `stall_enable.fpga_emu` compiled with `-DPART=STALL_ENABLE`