System Object Generation with the FIL Wizard

Step 1: Set Up FPGA Design Software Tools

 AMD Software

Set up your system environment for accessing AMD^® tools from MATLAB^® with the function hdlsetuptoolpath. This function adds the specified installation folder to the MATLAB search path.

• AMD ISE

  hdlsetuptoolpath('ToolName','Xilinx ISE','ToolPath','C:\Xilinx\14.7\ISE_DS\ISE\bin\nt64')

  This example assumes that the AMD ISE design suite is installed at C:\Xilinx\14.7\ISE_DS\ISE\bin\nt64.

• AMD Vivado^®

  hdlsetuptoolpath('ToolName','Xilinx Vivado','ToolPath','C:\Xilinx\Vivado\2023.1\bin\vivado.bat')

  This example assumes that AMD Vivado is installed at C:\Xilinx\Vivado\2023.1\bin\vivado.bat.

 Intel Software

Set up your system environment for accessing Intel^® tools from MATLAB with the function hdlsetuptoolpath. This function adds the specified installation folder to the MATLAB search path. For example:

hdlsetuptoolpath('ToolName','Altera Quartus II','ToolPath','C:\Altera\12.0\quartus\bin64')

This example assumes that the Intel FPGA design software is installed at C:\Altera\12.0\quartus\bin64.

 Microchip Software

Set up your system environment for accessing Microchip tools from MATLAB with the function hdlsetuptoolpath. This function adds the specified installation folder to the MATLAB search path. For example:

hdlsetuptoolpath('ToolName','Microchip Libero SoC','ToolPath','C:\Microsemi\Libero_SoC_v12.0\Designer\bin\libero.exe')

This example assumes that the Microchip FPGA design software is installed at C:\Microsemi\Libero_SoC_v12.0\Designer\bin.

Step 2: Start FIL Wizard

Open the FPGA-in-the-Loop Wizard.

In the MATLAB command window, type the following:

>> filWizard

To restore a previous session, use this command:

filWizard('./Subsystem_fil/Subsystem_fil.mat')

Step 3: Set FIL Options for System Object

(This page is for FIL System object™. For Simulink^® block FIL options, see Step 3: Set FIL Options for FIL Block.)

On the FIL Options page:

1. FIL Simulation with: Select MATLAB System Object.

2. Board Name: Select an FPGA development board. If you have not yet downloaded an HDL Verifier™ FPGA board support package, see Download FPGA Board Support Package. (If you do not see any boards listed, then you have not yet downloaded a support package). If you plan to define a custom board yourself, see FPGA Board Customization.

3. FPGA-in-the-Loop Connection: Select the FIL simulation connection method. The options in the drop-down menu update depend on the connection methods supported for the target board you selected. If the target board and HDL Verifier support the connection, you can choose Ethernet, JTAG, PCI Express, or USB Ethernet.

4. MATLAB/FPGA Synchronization Mode: For supported SoC boards and interfaces, choose between lockstep or free-running FPGA modes.

   • Lockstep — The DUT on the FPGA operates in lockstep with MATLAB. The hardware clock is generated by MATLAB, and every clock cycle execution in the DUT corresponds to a sample step in MATLAB. This mode provides cycle-accurate simulation.

   • Free-running FPGA — The DUT on the FPGA runs asynchronously with MATLAB. The hardware clock runs continuously on the FPGA. This mode allows the DUT to run at full speed and only communicate with MATLAB upon request.

   For more information, see What Is Free-Running FPGA-in-the-Loop?

5. Advanced Options:

   When you select an Ethernet connection for an FPGA board, you can adjust the board IP and MAC addresses, if necessary. If the board includes a processing unit, use the Guided Hardware Setup to configure the SD card.

   Option	Instructions
   Board IP address	Use this option for setting the IP address of the board if it is not the default IP address (192.168.0.2). If the default board IP address (192.168.0.2) is in use by another device, or you need a different subnet, change the Board IP address according to the following guidelines: The subnet address, typically the first three bytes of board IP address, must be the same as the subnet of the host IP address. The last byte of the board IP address must be different from the last byte of the host IP address. The board IP address must not conflict with the IP addresses of other computers. For example, if the host IP address is 192.168.8.2, then you can use 192.168.8.3, if available.
   Board MAC address	Under most circumstances, you do not need to change the board MAC address. If you connect more than one FPGA development board to a single host computer, change the board MAC address for any additional boards so that each address is unique. You must have a separate NIC for each board. To change the Board MAC address, click in the Board MAC address field. Specify an address that is different from that belonging to any other device attached to your computer. To obtain the Board MAC address for a specific FPGA development board, refer to the label affixed to the board or consult the product documentation.

   • FPGA system clock frequency (MHz) — Enter a target clock frequency. For Intel boards and AMD ISE-supported boards, filWizard checks the requested frequency against those possible for the requested board. If the requested frequency is not possible for this board, filWizard returns an error and suggests an alternate frequency. For AMD Vivado-supported boards, or PCI Express^® boards, filWizard cannot check the frequency. The synthesis tools make a best effort attempt at the requested frequency but may choose an alternate frequency if the specified frequency was not achievable. The default is 25 MHz.

   • Enable data buffering on FPGA — Select this option to enhance simulation performance. When selected, FIL utilizes BRAMs on the FPGA to buffer Ethernet packets in frame-based processing mode. Clear this parameter when BRAM resources are scarce in your design. Available for Ethernet connection only.

6. Click Next.

Step 4: Add HDL Source Files for System Object

(This page is for FIL System object. For Simulink block HDL source files, see Step 4: Add HDL Source Files for FIL Block.)

On the Source Files page:

1. Specify the HDL design to be cosimulated in the FPGA. These files are the HDL design files to be verified on the FPGA board.

   Indicate source files by clicking Add. Select files using the file selection dialog box.

   The FIL wizard attempts to identify the source file types. If any of the file types is not what you expect, you can change it by selecting from the File Type drop-down list. Acceptable file types are:

   • VHDL^®

   • Verilog^®

   • Netlist

   • Tcl script

   • Constraints

   • Others

     "Others" refers to the following:

     • For Intel, files specified as Other are added to the FPGA project, but they have no impact on the generated block. For example, you can put some comments in a readme file and include it in this file list.

     • For AMD, files specified as Other can be any file accepted by AMD ISE. ISE looks at the file extension to determine how to use this file. For example, if you add foo.vhd to the list and specify it as Other, ISE treats the file as a VHDL file.

2. Specify which file contains the top-level HDL file.

   Check the box on the row of the HDL file that contains the top-level HDL module in the column titled Top-level. The FIL wizard automatically fills the Top-level module name field with the name of the selected HDL file. If the top-level module name and file name do not match, you can manually change the top-level module name in this dialog box. Indicate the top-level module name before you continue.

3. (Optional) To display the full paths to the source files, check the box titled Show full paths to source files.

4. Click Next.

Step 5: Verify DUT I/O Ports for System Object

(This page is for FIL with a System object. For Simulink, see Step 5: Verify DUT I/O Ports for FIL Block.)

On the DUT I/O Ports page:

1. Review the port listing. The FIL wizard parses the top-level HDL module to obtain all the I/O ports and display them in the DUT I/O Ports table. The parser attempts to determine the port types from the port names. The wizard then displays these signals under Port Type. Select from:

   • Clock

   • Reset

   • Clock enable

   • Data

   • Streaming data – available when Synchronization Mode is set to Free-running FPGA.

   • Streaming valid – available when Synchronization Mode is set to Free-running FPGA.

   • Streaming ready – available when Synchronization Mode is set to Free-running FPGA.

   • Control data – available when Synchronization Mode is set to Free-running FPGA.

   Make sure all input/output/reset ports/clocks are mapped as you expect. If the parser assigned an incorrect port type for any port, you can manually change the signal. For synchronous design, specify a Clock, Reset, or, if desired, a Clock enable signal. The port types specified in this table must be the same as in the HDL code. There must be at least one output port.

   Select Manually enter port information to add or remove signals.

   Click Regenerate to reload the table with the original port definitions (from the HDL code).

2. Click Next.

Step 6: Specify Output Types for System Object

(This page is for FIL System object. For Simulink block output types, see Step 6: Specify Output Types for FIL Block.)

On the Output Types page:

1. Specify output data types. The wizard assigns data types. If any output data type is not what you expect, manually change the type.

   Select from:

   • Fixedpoint

   • Integer

   • Logical

   The data type can depend on the specified bit width.

   You can specify the output type to be Signed, Unsigned, or Fraction Length.

2. Click Next.

Step 7: Specify Build Options for System Object

(This page is for FIL System object. For Simulink, see Step 7: Specify Build Options for FIL Block.)

On the Build Options page:

1. Specify the folder for the output files. You can use the default option. Usually the default is a subfolder named after the top-level module, located under the current folder.

2. Note the locations of the ISE project file and the FPGA programming file in the Summary. You may need those two files for advanced operations on the FIL block mask.

Step 8: Initiate Build

Click Build to initiate FIL System object generation.

1. The FIL wizard generates the following files:

   • In the ./toplevel_fil/ folder, a MATLAB function named toplevel_programFPGA.m, where toplevel is the name of the HDL top level. This file contains the code to download the FPGA programming file to the FPGA.

     function toplevel_programFPGA
     
       %Load the bitstream in the FPGA
       filProgramFPGA('AMD', '/dir/mybitstream.bit', 1);
     end

   • A MATLAB file named toplevel_fil.m, where toplevel is the name of the HDL top level. This file contains a class definition derived from hdlverifier.FILSimulation and initializes the private properties. This file is located in the current folder.

     The following is a sample of a class definition file generated using the FIL wizard from a DUT named fft8.

     classdef fft8_fil <  hdlverifier.FILSimulation
     % fft8_fil is a filWizard generated class used for FPGA-In-the-Loop
     %   simulation with the 'fft8' DUT.
     %   fft8_fil connects MATLAB with a FPGA and cosimulate with it by 
     %   writing inputs in the FPGA and reading outputs from the FPGA.
     %
     %   MYFIL = fft8_fil
     %
     %   FIL syntax:
     %
     %   [out1, out2, ...] = MYFIL(in1, in2, ...) connect to the FPGA,
     %   write in1, in2, ... to the FPGA and read out1, out2, ... from 
     %   the FPGA
     %
     %   fft8_fil methods:
     %
     %   release     - Allow property value and input characteristics changes, and
     %                 release connection to FPGA board
     %   clone       - Create fft8_fil object with same property values
     %   isLocked    - Locked status (logical)
     %   programFPGA - Load the programming file in the FPGA
     %
     %   fft8_fil properties:
     %
     %   DUTName                  - DUT top level name
     %   InputSignals             - Input paths in the HDL code
     %   InputBitWidths           - Width in bit of the inputs
     %   OutputSignals            - Output paths in the HDL code
     %   OutputBitWidths          - Width in bit of the outputs
     %   OutputDataTypes          - Data type of the outputs
     %   OutputSigned             - Sign of the outputs
     %   OutputFractionLengths    - Fraction lengths of the outputs
     %   OutputDownsampling       - Downsampling factor and phase of the outputs
     %   OverclockingFactor       - Overclocking factor of the hardware
     %   SourceFrameSize          - Frame size of the source (only for HDL source block) 
     %   Connection               - Parameters for the connection with the board
     %   FPGAVendor               - Name of the FPGA chip vendor
     %   FPGABoard                - Name of the FPGA board
     %   FPGAProgrammingFile      - Path of the Programming file for the FPGA
     %   ScanChainPosition        - Position of the FPGA in the JTAG scan chain
     %
     %   File Name: fft8_fil.m
     %   Created: 26-Apr-2012 18:18:06
     % 
     %   Generated by FIL Wizard
     
         properties (Nontunable)
             DUTName = 'fft8';
         end
         
         methods
             function obj = fft8_fil
                 
                 %THE FOLLOWING PROTECTED PROPERTIES ARE SPECIFIC TO THE HW DUT
                 %AND MUST NOT BE EDITED (RERUN THE FIL WIZARD TO CHANGE THEM)
                 obj.InputSignals = char('Xin_re','Xin_im');
                 obj.InputBitWidths = [10,10];
                 obj.OutputSignals = char('Xout_re','Xout_im');
                 obj.OutputBitWidths = [13,13];
                 obj.Connection = char('UDP','192.168.0.2','00-0A-35-02-21-8A'); 
                 obj.FPGAVendor = 'AMD';
                 obj.FPGABoard = 'XUP Atlys Spartan-6 development board';
                 obj.ScanChainPosition = 1 ;
                 
                 %THE FOLLOWING PUBLIC PROPERTIES ARE RELATED TO THE SIMULATION
                 %AND CAN BE EDITED WITHOUT RERUNING THE FIL WIZARD
                 obj.OutputSigned = [true,true];
                 obj.OutputDataTypes = char('fixedpoint','fixedpoint');
                 obj.OutputFractionLengths = [9,9];
                 obj.OutputDownsampling = [1,0];
                 obj.OverclockingFactor = 1;
                 obj.SourceFramieSize = 1;
                 obj.FPGAProgrammingFile = 'S:\MATLAB\demo\fft8_fil\fft8_fil.bit';
             end
         end
     end
     

2. The FIL wizard opens a command window.

   • In this window, the FPGA design software performs synthesis, fit, PAR, and FPGA programming file generation.

   • When the process completes, a message in the command window prompts you to close the window.

     

Step 9: Integrate and Simulate

Create System Object

Create a custom FILSimulation System object from the class definition file derived using the FIL wizard. This code snippet creates an instance of the class and initializes all properties.

MYFIL = toplevel_fil

If you generated your FIL System object from the HDL Workflow Advisor, it is unlikely that you need to adjust any settings. If you generated your FIL System object using the FIL Wizard, you may want to adjust some settings. You can adjust any writable property using one of these methods:

• Change the property with the set method:

  MYFIL.set('FPGAProgrammingFile','c:\work\filfiles')

• Set the property directly:

  MYFIL.FPGAProgrammingFile='c:\work\filfiles'

• Edit toplevel_fil.m directly. If you edit the .m file, instantiate the object in the workspace again, if you had done so previously.

For details about the object properties, see hdlverifier.FILSimulation.

Load Programming Files onto FPGA

You can program the FPGA using either the programFPGA function, or the programFPGA method of the FIL System object. If you have not yet performed the Guided Hardware Setup, do so now before loading the programming files.

• programFPGA function:

  ./toplevel_fil/toplevel_programFPGA

• programFPGA method:

  MYFIL.programFPGA

  MYFIL is an instance of a FILSimulation object.

Run Simulation

1. Call the System object in your MATLAB code.

2. Run your MATLAB code as you normally would. Make sure that you have performed the Guided Hardware Setup before beginning.

   The first call to the object establishes communication with the FPGA board.