AC Fixed Tutorial

DirectProgramming/DPC++FPGA/Tutorials/Features/ac_types/ac_fixed/CMakeLists.txt

@@ -0,0 +1,20 @@
+if(UNIX)
+    # Direct CMake to use dpcpp rather than the default C++ compiler/linker
+    set(CMAKE_CXX_COMPILER dpcpp)
+else() # Windows
+    # Force CMake to use dpcpp rather than the default C++ compiler/linker 
+    # (needed on Windows only)
+    include (CMakeForceCompiler)
+    CMAKE_FORCE_CXX_COMPILER (dpcpp IntelDPCPP)
+    include (Platform/Windows-Clang)
+endif()
+
+cmake_minimum_required (VERSION 3.4)
+
+project(ACFixed CXX)
+
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+
+add_subdirectory (src)

DirectProgramming/DPC++FPGA/Tutorials/Features/ac_types/ac_fixed/License.txt

@@ -0,0 +1,23 @@
+Copyright Intel Corporation
+
+SPDX-License-Identifier: MIT
+https://opensource.org/licenses/MIT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

DirectProgramming/DPC++FPGA/Tutorials/Features/ac_types/ac_fixed/README.md

@@ -0,0 +1,260 @@
+# Using the Algorithmic C Fixed Point Data-type 'ac_fixed'
+
+This FPGA tutorial demonstrates how to use the Algorithmic C (AC) Data-type `ac_fixed` and some best practices.
+
+***Documentation***:  The [DPC++ FPGA Code Samples Guide](https://software.intel.com/content/www/us/en/develop/articles/explore-dpcpp-through-intel-fpga-code-samples.html) helps you to navigate the samples and build your knowledge of DPC++ for FPGA. <br>
+The [oneAPI DPC++ FPGA Optimization Guide](https://software.intel.com/content/www/us/en/develop/documentation/oneapi-fpga-optimization-guide) is the reference manual for targeting FPGAs through DPC++. <br>
+The [oneAPI Programming Guide](https://software.intel.com/en-us/oneapi-programming-guide) is a general resource for target-independent DPC++ programming.
+
+| Optimized for                     | Description
+---                                 |---
+| OS                                | Linux* Ubuntu* 18.04/20.04, RHEL*/CentOS* 8, SUSE* 15; Windows* 10
+| Hardware                          | Intel® Programmable Acceleration Card (PAC) with Intel Arria® 10 GX FPGA <br> Intel® FPGA Programmable Acceleration Card (PAC) D5005 (with Intel Stratix® 10 SX) <br> Intel® FPGA 3rd party / custom platforms with oneAPI support <br> *__Note__: Intel® FPGA PAC hardware is only compatible with Ubuntu 18.04* 
+| Software                          | Intel® oneAPI DPC++ Compiler <br> Intel® FPGA Add-On for oneAPI Base Toolkit
+| What you will learn               | How different methods of `ac_fixed` number construction affect hardware resource utilization <br> Recommended method for constructing `ac_fixed` numbers in your kernel <br> Accessing and using the `ac_fixed` math library functions <br> Trading off accuracy of results for reduced resource usage on the FPGA
+| Time to complete                  | 30 minutes
+
+
+
+## Purpose
+
+This FPGA tutorial shows how to use the `ac_fixed` type with some simple examples.
+
+This data-type can be used in place of native floating point types to generate area efficient and optimized designs for the FPGA. For example, operations which do not utilize all of the bits the native types are good candidates for replacement with `ac_fixed` type.
+
+This tutorials shows the recommended method for constructing an `ac_fixed` number, some examples of using the fixed point math library functions and how they can be used to reduce the area of the hardware generated by the compiler by trading-off accuracy of the mathematical operations.
+
+### Simple Code Example
+
+An `ac_fixed` number can be defined as follows:
+```cpp
+ac_fixed<W, I, S> a;
+```
+Here W specifies the width and S specifies the sign of the number. One of the W bits is used to store the sign information. The second parameter I is an integer that specifies the location of the fixed point relative to the most significant bit.
+
+The type also provides two more optional parameters for controlling the overflow and rounding modes. For more details on the type, rounding and overflow modes and the range of values supported with different width parameterization please refer to the file `ac_data_types_ref.pdf`.
+
+To use this type in your code, you must include the following header:
+
+```cpp
+#include <sycl/ext/intel/ac_types/ac_fixed.hpp>
+```
+
+Additionally, you must use the flag `-qactypes` in order to ensure that the headers are correctly included.
+
+### Recommended method for constructing ac_fixed numbers
+
+The compiler uses significant FPGA resources to convert double precision (and single precision) floating-point values to `ac_fixed` values. The kernel `ConstructFromFloat` constructs an `ac_fixed` object from an accessor to a native `float` type.
+
+In contrast, the kernel `ConstructFromACFixed` constructs an `ac_fixed` object from an accessor to another `ac_fixed` object. This consumes far less area than the previous kernel. See the section on examining the reports below to understand where to look for this difference within the optimization reports.
+
+### Using the ac_fixed math functions
+
+To use this type in your code, you must include the following header:
+
+```cpp
+#include <sycl/ext/intel/ac_types/ac_fixed_math.hpp>
+```
+
+The flag `-qactypes` will ensure that the compiler includes the header and links against the necessary libraries for emulation of the math library functions.
+
+This tutorial design contains two kernels `CalculateWithFloat` and `CalculateWithACFixed`. Both calculate the simple expression:
+```cpp
+  square_root ( sine(x) * sine(x) + cosine(x) * cosine(x) )
+```
+for some input `x`.
+
+The kernel `CalculateWithFloat` uses floating point values and the standard math library while `CalculateWithACFixed` uses `ac_fixed` values and the `ac_fixed` math library. The `ac_fixed` inputs are instantiated with the following parameters:
+
+```cpp
+  W = 10, I = 3, S = true
+```
+
+Clearly, the `ac_fixed` numbers are smaller in size than floating point numbers. This results in reduction of the FPGA resources utilized by the functions at the expense of accuracy. To see the trade-offs between accuracy compare the numeric results of the operations. The area utilization differences will be discussed in the section on `Examining the reports`.
+
+When you use the `ac_fixed` library, keep the following points in mind:
+
+1. Input Bit Width and Input Value Range Limits
+
+    The fixed-point math functions have bit width and input value range requirements. All bit width and input value range requirements are documented at the top of the ac_fixed_math.hpp file. For example, the `sin_fixed` and `cos_fixed` functions require the integer part's bit width to be 3, and the input value range to be within [-pi, pi].
+
+2. Return Types
+
+    For fixed-point functions, each function has a default return type. Assigning the result to a non-default return type triggers a type conversion and can cause an increase in logic use or a loss of accuracy in your results.  All return types are documented at the top of the ac_fixed_math.hpp file. For example, for `sin_fixed` and `cos_fixed`, the input type is `ac_fixed<W, 3, true>`, and the output type is `ac_fixed<W-1, 2, true>`.
+
+3. Accuracy
+ - Floating point vs Fixed point
+
+    The host program (`main()` function) for this tutorial gives you an estimate of the difference between the correct result and the result provided by the math library functions. The floating point version (which has a greater bit width in this case) generates a more accurate result.
+
+ - Emulation vs Simulation for fixed point math operations
+
+    Due to the differences in the internal math implementations, the results from `ac_fixed` math functions in simulation and emulation might not always be bit-accurate. In this example you can observe the difference between emulation and simulation.
+
+## Key Concepts
+ * Constructing an `ac_fixed` from a `float` or `double` value will be much more area intensive than constructing one from another `ac_fixed`.
+ * The `ac_fixed` math library provides a set of functions for various math operations.
+ * The functions can be used to trade off accuracy of results for reduced resource usage on the FPGA.
+ * When using these functions, one must be mindful of the widths of the input and return types and follow the parameterization laid out in the header file for optimal results.
+
+## License
+
+Code samples are licensed under the MIT license. See
+[License.txt](https://github.com/oneapi-src/oneAPI-samples/blob/master/License.txt) for details.
+
+
+## Building the `ac_fixed` Tutorial
+
+### Include Files
+
+The included header `dpc_common.hpp` is located at `%ONEAPI_ROOT%\dev-utilities\latest\include` on your development system.
+
+### Running Samples in DevCloud
+If running a sample in the Intel DevCloud, remember that you must specify the type of compute node and whether to run in batch or interactive mode. Compiles to FPGA are only supported on fpga_compile nodes. Executing programs on FPGA hardware is only supported on fpga_runtime nodes of the appropriate type, such as fpga_runtime:arria10 or fpga_runtime:stratix10.  Neither compiling nor executing programs on FPGA hardware are supported on the login nodes. For more information, see the Intel® oneAPI Base Toolkit Get Started Guide ([https://devcloud.intel.com/oneapi/documentation/base-toolkit/](https://devcloud.intel.com/oneapi/documentation/base-toolkit/)).
+
+When compiling for FPGA hardware, it is recommended to increase the job timeout to 12h.
+
+### On a Linux* System
+
+1. Install the design in `build` directory from the design directory by running `cmake`:
+
+   ```bash
+   mkdir build
+   cd build
+   ```
+
+   If you are compiling for the Intel® PAC with Intel Arria® 10 GX FPGA, run `cmake` using the command:
+
+   ```bash
+   cmake ..
+   ```
+
+   Alternatively, to compile for the Intel® FPGA PAC D5005 (with Intel Stratix® 10 SX), run `cmake` using the command:
+
+   ```bash
+   cmake .. -DFPGA_BOARD=intel_s10sx_pac:pac_s10
+   ```
+   You can also compile for a custom FPGA platform. Ensure that the board support package is installed on your system. Then run `cmake` using the command:
+   ```bash
+   cmake .. -DFPGA_BOARD=<board-support-package>:<board-variant>
+   ```
+
+2. Compile the design using the generated `Makefile`. The following four build targets are provided that match the recommended development flow:
+
+   * Compile and run for emulation (fast compile time, targets emulates an FPGA device) using:
+
+     ```bash
+     make fpga_emu
+     ```
+
+   * Generate HTML optimization reports using:
+
+     ```bash
+     make report
+     ```
+
+   * Compile and run on FPGA hardware (longer compile time, targets an FPGA device) using:
+
+     ```bash
+     make fpga
+     ```
+
+3. (Optional) As the above hardware compile may take several hours to complete, FPGA precompiled binaries (compatible with Linux* Ubuntu* 18.04) can be downloaded <a href="https://iotdk.intel.com/fpga-precompiled-binaries/latest/ac_fixed.fpga.tar.gz" download>here</a>.
+
+### On a Windows* System
+
+1. Generate the `Makefile` by running `cmake`.
+     ```
+   mkdir build
+   cd build
+   ```
+   To compile for the Intel® PAC with Intel Arria® 10 GX FPGA, run `cmake` using the command:  
+    ```
+    cmake -G "NMake Makefiles" ..
+   ```
+   Alternatively, to compile for the Intel® FPGA PAC D5005 (with Intel Stratix® 10 SX), run `cmake` using the command:
+
+   ```
+   cmake -G "NMake Makefiles" .. -DFPGA_BOARD=intel_s10sx_pac:pac_s10
+   ```
+   You can also compile for a custom FPGA platform. Ensure that the board support package is installed on your system. Then run `cmake` using the command:
+   ```
+   cmake -G "NMake Makefiles" .. -DFPGA_BOARD=<board-support-package>:<board-variant>
+   ```
+
+2. Compile the design through the generated `Makefile`. The following build targets are provided, matching the recommended development flow:
+
+   * Compile for emulation (fast compile time, targets emulated FPGA device): 
+     ```
+     nmake fpga_emu
+     ```
+   * Generate the optimization report: 
+     ```
+     nmake report
+     ``` 
+   * Compile for FPGA hardware (longer compile time, targets FPGA device):
+     ```
+     nmake fpga
+     ``` 
+
+*Note:* The Intel® PAC with Intel Arria® 10 GX FPGA and Intel® FPGA PAC D5005 (with Intel Stratix® 10 SX) do not support Windows*. Compiling to FPGA hardware on Windows* requires a third-party or custom Board Support Package (BSP) with Windows* support.
+
+### In Third-Party Integrated Development Environments (IDEs)
+
+You can compile and run this tutorial in the Eclipse* IDE (in Linux*) and the Visual Studio* IDE (in Windows*).
+For instructions, refer to the following link: [Intel® oneAPI DPC++ FPGA Workflows on Third-Party IDEs](https://software.intel.com/en-us/articles/intel-oneapi-dpcpp-fpga-workflow-on-ide)
+
+## Examining the Reports
+
+Locate the pair of `report.html` files in either:
+
+* **Report-only compile**:  `ac_fixed_report.prj`
+* **FPGA hardware compile**: `ac_fixed.prj`
+
+Scroll down on the Summary page of the report and expand the section titled `Compile Estimated Kernel Resource Utilization Summary`. Observe how the kernel `ConstructFromACFixed` consumes lesser resources than the kernel named `ConstructFromFloat`. Similarly, observe how the kernel named `CaclulateWithACFixed` consumes lesser FPGA resources than `CalculateWithFloat`.
+
+## Running the Sample
+
+1. Run the sample on the FPGA emulator (the kernel executes on the CPU):
+
+   ```bash
+   ./ac_fixed.fpga_emu    # Linux
+   ac_fixed.fpga_emu.exe  # Windows
+   ```
+
+2. Run the sample on the FPGA device
+
+   ```bash
+   ./ac_fixed.fpga             # Linux
+   ```
+
+### Example of Output
+
+```txt
+Constructed from float:         3.6416015625
+Constructed from ac_fixed:      3.6416015625
+
+MAX DIFF for ac_fixed<10, 3, true>:  0.0078125
+MAX DIFF for float:                  9.53674e-07
+
+result(fixed point): 1
+result(float):       1
+
+result(fixed point): 0.992188
+result(float):       1
+
+result(fixed point): 1
+result(float):       1
+
+result(fixed point): 1
+result(float):       1
+
+result(fixed point): 0.992188
+result(float):       1
+
+PASSED
+```
+
+### Discussion of Results
+
+You will be able to obtain a smaller hardware footprint for your kernel by ensuring that the `ac_fixed` numbers are constructed from `float` or `double` numbers outside the kernel. Additionally, you can trade-off mathematical operation accuracy for a more resource efficient design by using the `ac_fixed` math library functions.

DirectProgramming/DPC++FPGA/Tutorials/Features/ac_types/ac_fixed/ac_fixed.sln

@@ -0,0 +1,25 @@
+
+Microsoft Visual Studio Solution File, Format Version 12.00
+# Visual Studio 15
+VisualStudioVersion = 15.0.28307.705
+MinimumVisualStudioVersion = 10.0.40219.1
+Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "ac_fixed", "ac_fixed.vcxproj", "{73FCAD5C-4C93-4786-B662-A7273C515E22}"
+EndProject
+Global
+	GlobalSection(SolutionConfigurationPlatforms) = preSolution
+		Debug|x64 = Debug|x64
+		Release|x64 = Release|x64
+	EndGlobalSection
+	GlobalSection(ProjectConfigurationPlatforms) = postSolution
+		{73FCAD5C-4C93-4786-B662-A7273C515E22}.Debug|x64.ActiveCfg = Debug|x64
+		{73FCAD5C-4C93-4786-B662-A7273C515E22}.Debug|x64.Build.0 = Debug|x64
+		{73FCAD5C-4C93-4786-B662-A7273C515E22}.Release|x64.ActiveCfg = Release|x64
+		{73FCAD5C-4C93-4786-B662-A7273C515E22}.Release|x64.Build.0 = Release|x64
+	EndGlobalSection
+	GlobalSection(SolutionProperties) = preSolution
+		HideSolutionNode = FALSE
+	EndGlobalSection
+	GlobalSection(ExtensibilityGlobals) = postSolution
+		SolutionGuid = {DE911CD1-4F98-4391-BD43-B02212357F5E}
+	EndGlobalSection
+EndGlobal