Skip to content

Latest commit

 

History

History
402 lines (288 loc) · 17.5 KB

README.md

File metadata and controls

402 lines (288 loc) · 17.5 KB

Platform Designer Sample

This example design shows how to use an FPGA IP produced with the Intel® oneAPI DPC++/C++ Compiler with the Intel® Quartus® Prime Pro Edition software suite. Please refer to Platform Designer Standard code sample when targeting a Cyclone® V SoC Board.

Optimized for Description
OS Ubuntu* 20.04
RHEL*/CentOS* 8
SUSE* 15
Windows* 10, 11
Windows Server* 2019
Hardware This process applies to any Intel® FPGA that is supported by the DPC++/C++ compiler, but the sample Intel® Quartus® Prime Pro Edition project targets the Intel® Arria® 10 SX SoC Development Kit
Software Intel® oneAPI DPC++/C++ Compiler
Intel® Quartus® Prime Pro Edition Version 22.3 or later
What you will learn How to integrate an RTL IP generated from a SYCL kernel with an Intel® Quartus® Prime Pro Edition project
Time to complete 1 hour

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.

To use the simulator flow, Intel® Quartus® Prime Pro Edition and one of the following simulators must be installed and accessible through your PATH:

  • Questa*-Intel® FPGA Edition
  • Questa*-Intel® FPGA Starter Edition
  • Questa* Advanced Simulator
  • ModelSim® SE

To use the hardware compile flow, Intel® Quartus® Prime Pro Edition must be installed and accessible through your PATH.

Prerequisites

This sample is part of the FPGA code samples. It is categorized as a Tier 1 sample that helps you getting started.

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:#f96,stroke:#333,stroke-width:1px,color:#fff
   style tier2 fill:#0071c1,stroke:#0071c1,stroke-width:1px,color:#fff
   style tier3 fill:#0071c1,stroke:#0071c1,stroke-width:1px,color:#fff
   style tier4 fill:#0071c1,stroke:#0071c1,stroke-width:1px,color:#fff
Loading

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, etc.

Purpose

This sample demonstrates how to:

  • Compile a SYCL kernel into an IP component
  • Add the IP component to an Intel® Platform Designer system
  • Add the Platform Designer system to a top-level entity in a Intel® Quartus® Prime project
  • Compile and run the resulting system on a hardware board.

The sample uses the JTAG to Avalon® Master Bridge Intel FPGA IP to connect your IP component to the JTAG control interface. You can use the System Console application to control and observe the behavior of your IP component.

This example is intended for users interested in creating standalone modules that can be included in Intel® Quartus® Prime projects. It serves as a minimal example, and while it targets a specific board, a user familiar with the Intel® Quartus® Prime Software Suite should be able to easily port this design to other hardware.

Key Implementation Details

This tutorial is structured with four source code directories.

Source Directory Description
add_oneapi The source and build scripts needed to compile a simple IP using oneAPI
add_quartus_sln An example of the project files that are created using the Intel® Quartus® Prime GUI
starting_files The minimal source files you need to create a Intel® Quartus® Prime project. Additional project files are created using the Intel® Quartus® Prime GUI.
system_console Scripts for controlling the System Console application while you test the design in hardware

Board-specific Considerations

This design is intended to work with the Intel® Arria® 10 SX SoC Development Kit. These board-specific configurations are not guaranteed to work with different boards:

  1. Choose 10AS066N3F40E2SG device to match the devkit
  2. Choose pin PIN_AM10 to drive the i_clk signal
  3. Choose pin PIN_AR23 to drive the fpga_led signal
  4. Choose pin PIN_AV21 to drive the reset_button_n signal
  5. Use jtag.sdc from the Intel® Arria® 10 SoC Golden Hardware Reference Design (GHRD) source code.

Building the platform_designer 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 located 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*.

Follow these steps to compile and test the design:

  1. Compile the SYCL code to RTL. Although this design supports emulation and simulation like other FPGA code samples, they are not the focus of this tutorial. The emulation and simulation commands have been omitted.

    Linux:

    $> mkdir build
$> cd build
$> cmake ../add_oneapi
$> make report
$> cd ..

    Windows:

    > mkdir build
> cd build
> cmake -G "NMake Makefiles" ../add_oneapi
> nmake report
> cd ..

  2. From the same terminal, prepare a project directory called add_quartus for the Intel® Quartus® Prime project and copy the source files add.sv and jtag.sdc from the starting_files directory into it. Then launch the Intel® Quartus® Prime Pro Edition GUI, and create a new Intel® Quartus® Prime project using the 'New Project' wizard.

    Note: You may confirm your Intel® Quartus® Prime project settings by comparing with the sample Intel® Quartus® Prime project included in the add_quartus_sln directory.

    Linux:

    $> mkdir add_quartus
$> cp -r starting_files/* add_quartus/
$> cd add_quartus
$> quartus

    Windows:

    > mkdir add_quartus
> ROBOCOPY starting_files/ add_quartus/ /S /NFL /NDL
> cd add_quartus
> quartus.exe

    1. Set the project directory to be the add_quartus directory.

    2. Set the top-level entity to be add to make project management easier.

    3. Make sure you choose an appropriate device. See Board-specific Considerations above.

    4. Choose Empty Project when prompted to select a project type.

    5. Add the source file add.sv and jtag.sdc to the design when the wizard prompts you. These may be copied from starting_files.

      add.sv is the top-level entity of this design. It instantiates an instance of the Platform Designer system that contains your simple SYCL HLS IP.

      jtag.sdc contains timing constraints for the JTAG IP.

  3. Copy the IP you generated in Step 1 to the Intel Quartus® Prime project.

    Linux:

    $> cd .. # navigate to build root if not there already
$> cp -r build/add.report.prj/ add_quartus/

    Windows:

    > cd .. # navigate to build root if not there already
> ROBOCOPY build\add.report.prj\ add_quartus\add.report.prj\ /S /NFL /NDL

  4. Create the Platform Designer system.

    1. Open Platform Designer from the Intel® Quartus® Prime GUI:

    2. Create a new system by clicking the 'New Platform Designer System' button () and name it add_kernel_wrapper.qsys.

    3. Disconnect the clock from the Reset Bridge IP:

    4. Configure the Reset Bridge IP as shown:

    5. Add the following IP to your system:

      • Basic Functions > Bridges and Adaptors > Memory Mapped > JTAG to Avalon Master Bridge Intel® FPGA IP

      • oneAPI > add_report_di

      Note: If you cannot see the oneAPI IP component, refresh Platform Designer by clicking File > Refresh System

    6. Connect the modules as shown:

      Don't forget to export the irq_add and exception_add signals. The provided top-level RTL file (add.sv) uses the generated IP. Following these naming conventions allows the IP to connect to this handwritten RTL.

    7. Save the system by clicking File > Save

    8. Make sure there are no errors in the 'System Messages' panel.

    9. Generate the system so that it can be included in the Intel® Quartus® Prime project by clicking Generate HDL...

    10. Close Platform Designer.

  5. In the Intel® Quartus® Prime window, run Analysis and Elaboration by clicking 'Start Analysis and Elaboration'.

  6. Select pins for the i_clk and reset_button_n inputs and fpga_led output. The JTAG to Avalon® Master Bridge Intel FPGA IP handles the connection between your design and the JTAG pins on your board automatically.

    1. Open the pin planner using Assignments > Pin Planner in the main Intel® Quartus® Prime GUI. Consult the data sheet for your board to choose an appropriate clock input. In this project, the PIN_AM10 was chosen because it supplies a 100MHz clock signal in the the GHRD source code (see link in Board-specifc Considerations).

    2. Assign pins for the fpga_led and reset_button_n signals using the same method:

      Pin planner from GHRD:

      Final pin planner configuration:

      Note: If you cannot see the pin details, click the All Pins button in the bottom left corner of the Pin Planner GUI.

      Note: Make sure you choose 'LVDS' for the I/O standard of i_clk, the pin location will be automatically populated for i_clk(n).

  7. Add the timing constraints.

    1. If you are using the Intel® Arria® 10 SX SoC Dev Kit, you can find a timing constraints file for the JTAG interface (jtag.sdc) in the GHRD. This file was added during project creation.

    2. Create a new Synopsis Design Constraints (SDC) file named add.sdc and insert a new clock called i_clk to match the clock you defined in add.sv. Set the period to be 10ns:

      set_time_format -unit ns -decimal_places 3
create_clock -name i_clk -period 10 [get_ports {i_clk}]

    3. Cut the clock paths for asynchronous I/O:

      set_false_path -from [get_ports {reset_button_n}] -to * 
set_false_path -from [get_ports {fpga_led}] -to *
set_false_path -from * -to [get_ports {fpga_led}]

  8. Compile the full design by clicking the 'Start Compilation' button in the Intel® Quartus® Prime GUI.

  9. Copy the generated add.sof file to the system_console directory.

Linux:

$> cp add_quartus/output_files/add.sof system_console

Windows:

> xcopy add_quartus\output_files\add.sof system_console /Y

You may also build the SOF using the pre-generated Intel® Qupartus® Prime project in the add_quartus_sln directory by executing the included build_system.tcl script. This script has been verified against the latest version of Quartus® Prime Pro Edition software available at the time of writing (24.1). The script and pre-generated project may not work with other versions of Quartus® Prime.

Linux:

mkdir build_pd_system
cd build_pd_system
quartus_sh -t ../build_system.tcl

Windows:

mkdir build_pd_system
cd build_pd_system
quartus_sh -t ..\build_system.tcl

Additional Documentation

Running the Sample

Use the test.bat script in the system_console directory to flash the design to your development board, and launch the system console. The included .tcl script in the system_console directory demonstrates how to use the System Console to interact with your IP through the JTAG to Avalon® Master Bridge Intel FPGA IP on the FPGA.

To move the design to a different computer for testing, copy the entire system_console directory, along with add.sof.

See output:

> test.bat
Info: *******************************************************************
Info: Running Quartus Prime Programmer
<output from Intel® Quartus® Prime programmer>
Info: Quartus Prime Programmer was successful. 0 errors, 0 warnings
    Info: Peak virtual memory: 1309 megabytes
    Info: Processing ended: Wed Feb  8 15:26:54 2023
    Info: Elapsed time: 00:00:20
    Info: System process ID: 16980
Press any key to continue . . . 

---------------------------------------
---------------------------------------
 Welcome to Intel's FPGA System Console

<etc.>
---------------------------------------
%

At the % prompt, enter source test_add.tcl to exercise the hardware design.

% source test_add.tcl
Resetting IP...
TEST 1: READ OUTPUT AFTER RESET
Read outputs
  Data   (0x88): 0x00000000 0x00000000
  Status (0x00): 0x00050000 0x00000000
  finish (0x30): 0x00000000 0x00000000

TEST 2: LOAD INPUTS AND CHECK OUTPUT
press 'enter' key to load inputs ==>
Store 1 to address 0x80
Store 2 to address 0x84
Set 'Start' bit to 1
Check that IRQ LED is lit, then press 'enter' key to consume outputs ==>
Read outputs
  Data   (0x88): 0x00000003 0x00000000
  Status (0x00): 0x00050002 0x00000000
  finish (0x30): 0x00000001 0x00000000

press 'enter' key to load inputs ==>
Store 3 to address 0x80
Store 3 to address 0x84
Set 'Start' bit to 1
Check that IRQ LED is lit, then press 'enter' key to consume outputs ==>
Read outputs
  Data   (0x88): 0x00000006 0x00000000
  Status (0x00): 0x00050002 0x00000000
  finish (0x30): 0x00000001 0x00000000

TEST 3: LOAD INPUTS WITHOUT CHECKING OUTPUT
press 'enter' key to load inputs ==>
Store 5 to address 0x80
Store 4 to address 0x84
Set 'Start' bit to 1
Check that IRQ LED is lit, then press 'enter' key to overload inputs without consuming outputs ==>
Store 64 to address 0x80
Store 64 to address 0x84
Set 'Start' bit to 1
Check that IRQ LED is lit, then press 'enter' key to overload inputs without consuming outputs ==>
Store 7 to address 0x80
Store 8 to address 0x84
Set 'Start' bit to 1
Check that IRQ LED is lit, then press 'enter' key to consume outputs ==>
Read outputs
  Data   (0x88): 0x0000000f 0x00000000
  Status (0x00): 0x00050002 0x00000000
  finish (0x30): 0x00000003 0x00000000

TEST 4: READ OUTPUT AFTER NO PENDING INPUTS
press 'enter' key to consume outputs ==>
Read outputs
  Data   (0x88): 0x0000000f 0x00000000
  Status (0x00): 0x00050000 0x00000000
  finish (0x30): 0x00000000 0x00000000

Test complete.

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.