%% Accelerating Communications System Simulation Using FPGA-in-the-Loop
% This example uses FPGA-in-the-Loop (FIL) simulation to accelerate part of
% a communications system. The application uses the Viterbi Algorithm to
% decode a convolutional encoded random stream that is BPSK modulated, sent
% through an AWGN channel, and then demodulated. Using a sample-by-sample
% approach leads to a modest speedup over normal Simulink(R) simulation,
% while using the "Process as Frames" option leads to further speedup.
%
% This example uses the Communications Toolbox(TM) in conjunction with
% HDL Coder(TM) and HDL Verifier(TM) to show a design
% workflow for accelerating simulation using FPGA-in-the-loop.
%
%% Requirements and Prerequisites
% Tools required to run this example:
%
% * FPGA design software
% * One of the <matlab:helpview(fullfile(docroot,'toolbox','hdlverifier','helptargets.map'),'edalink_supported_devices')
% supported FPGA development boards> and accessories
% * For connection using Ethernet: Gigabit Ethernet Adapter installed on
% host computer, Gigabit Ethernet crossover cable
% * For connection using JTAG: USB Blaster I or II cable and driver for
% Intel FPGA boards. Digilent(R) JTAG cable and driver for Xilinx FPGA
% boards.
% * For connection using PCI Express(R): FPGA board installed into PCI
% Express slot of host computer.
%
% Requirements:
% MATLAB(R) and FPGA design software can either be locally installed on
% your computer or on a network accessible device. If you use software from
% the network you will need a second network adapter installed in your
% computer to provide a private network to the FPGA development board.
% Consult the hardware and networking guides for your computer to learn how
% to install the network adapter.
%

% Copyright 2010-2014 The MathWorks, Inc.

%% 1. Open and Execute the Simulink Model
% Open the model. Due to
% the large quantity of data to process, the simulation takes approximately 9
% seconds without FIL. We will improve the simulation speed in the following
% steps by using a FPGA-in-the-Loop.

%% 2. Generate HDL Code
% This step requires HDL Coder. If you do not have HDL Coder, you can use
% pre-generated HDL files in the current directory.
%
% If you are going to use these copied files, go directly to step 3. 
%
% Generate HDL code for the Viterbi block subsystem by
% performing these steps:
%
% *a.* Right click on the existing FIL block labeled |viterbi_block1|. Click on
% Delete to remove this block for code generation.
%
% *b.* In the *Modeling* tab, click *Model Settings*.
%
% *d.* Click on the *HDL Code Generation* pane and make sure the *hdlcoderviterbi_for_fil/viterbi_block*
% is selected.
%
% *e.* Click *Generate*.
%
% Alternatively, you can generate HDL code by entering the following
% command at the MATLAB prompt:
%
%%
%   makehdl('hdlcoderviterbi_for_fil/viterbi_block') 

%% 3. Set FPGA Design Software Environment
%
% Before using FPGA-in-the-Loop, make sure your system environment is set
% up properly for accessing FPGA design software. You can use the function
% *hdlsetuptoolpath* to add FPGA design software to the system path for the
% current MATLAB session.
%

%% 4. Run FPGA-in-the-Loop Wizard
% To launch the FIL Wizard, enter the
% following command at the MATLAB prompt:

%%
%   filWizard; 

%% 4.1 Hardware Options
% Select a board from the board list. Click Next to continue.

%% 4.2 Source Files
% *a.* Add all the previously generated HDL source files for the |Viterbi Block|
% subsystem.
%
% *b.* Select the file |viterbi_block.vhd| as the Top-level file. You may need
% to make the FPGA-in-the-Loop Wizard window wider in order to see these
% options.
%
% *c.* Notice that the |viterbi_block| has been entered for you as the default
% top-level module name. Click Next to continue.

%% 4.3 DUT I/O Ports
% Observe that the ports of the top-level module have been correctly identified.
% Click Next to continue.

%% 4.4 Build Options
% *a.* Select an output folder.
%
% *b.* Click Build to build the FIL block and programming file.
%
% During the build process, the following actions occur:
%
% * A FIL block named viterbi_block is generated in a new model.
%
%
% * After new model generation, the FIL Wizard opens a command window where the
% FPGA design software performs synthesis, mapping, place-and-route, timing
% analysis, and FPGA programming file generation.  For this block, these steps
% take about 20 minutes.
%
% When the FPGA design software process is finished, a message in the command window lets
% you know you can close the window. 

%% 5. Open and Complete the Simulink Model for FIL
%
% *a.* Open the <matlab:hdlcoderviterbi_for_fil hdlcoderviterbi_for_fil.mdl>
%
% *b.* Copy into it the previously generated FIL block and connect it either in
% parallel to or in place of the viterbi_block. Note that the original block has
% the inputs on the right. To make the FIL block have its inputs on the right,
% right click on the block and then click Rotate & Flip -> Flip Block.

%% 6. Configure FIL Block
% *a.* Double-click the FIL block in the model to open the block mask.
%
% *b.* Click *Load*.
%
% *c.* Click *OK* to close the block mask.

%% 7. Run FIL Simulation
% Run the simulation for 20480 seconds and observe the performance.
%
%%
%   FrameSize = 1;
%   tic; 
%   sim('hdlcoderviterbi_for_fil'); 
%   fs1 = toc

%%
% You can try setting the frame size to a larger number. For this example,
% the frame size is set to 1024 bytes.
%%
%   FrameSize = 1024;
%   tic; 
%   sim('hdlcoderviterbi_for_fil'); 
%   fs2 = toc

%%
% In our tests, the time to simulate was around 16 seconds when FrameSize = 1,
% which is about the same as simulating in Simulink without FIL, but the
% simulation time was decreased to around 12 seconds when the frame size was
% increased to 1024 using a Xilinx Spartan-6 SP605 board. This particular board
% and system gives an overall speedup of around 1.7 times faster, but other
% boards and communications system may be even faster.

%%
%   speedup = fs1 / fs2

%%
% By removing the Simulink block version and only simulating the FIL version,
% and by adding more blocks to the FIL part of the design and removing the
% Simulink scopes and displays as much as possible, even greater speedups are
% possible.

%%
% This concludes the Accelerating Communications System Simulation Using
% FPGA-In-the-Loop example.
%
