%% Getting Started with MATLAB Based SystemVerilog DPI Generation
% This example shows you how to generate a SystemVerilog DPI component for a
% programmable square-wave generator written in MATLAB, and
% export it to an HDL simulator.
%
% For demonstrative purposes, this example uses Modelsim 10.3c in 64-bit
% Windows 7. However, this same procedure can be easily replicated for
% other systems and simulators.
%
% Copyright 2013 The MathWorks, Inc.

%% Requirements and Prerequisites
% Products required for this example:
%
% * MATLAB Coder(R)
% * Simulators: Mentor Graphics(R) ModelSim(R)/QuestaSim(R) or Cadence(R) Incisive
% * One of the supported C compiler: Microsoft(R) Visual C++, or GNU GCC
%
%% MATLAB Design
% The MATLAB code used in this example demonstrates a simple programmable square wave
% generator. This example also provides a MATLAB test bench that exercises the
% design.

design='ProgSWGenerator';
testbench='ProgSWGenerator_tb';

%%
%
% * Design: <matlab:edit(fullfile(matlabroot,'toolbox','hdlverifier','hdlverifier_examples','svdpi_ProgSWGenerator','ProgSWGenerator')) ProgSWGenerator>
% * Test Bench: <matlab:edit(fullfile(matlabroot,'toolbox','hdlverifier','hdlverifier_examples','svdpi_ProgSWGenerator','ProgSWGenerator_tb')) ProgSWGenerator_tb>
%
%
% The following image illustrates the DPI component that is generated in this example:
%
% <<../svdpi_ProgSWGenerator1.png>>
%
% * The 'On_time' and 'Off_time' control the output signal duty cycle.
%
% For example, if On_time=1 and Off_time=1, the square wave generated will have 50% duty cycle. 

%% Simulate Design with Supplied MATLAB Testbench
% To make sure there are no run-time errors, and that the design meets the requirements, simulate the design with the supplied testbench prior to code generation.
% Enter the following command in MATLAB:
%  
%   ProgSWGenerator_tb
%
% It should plot the figure below:
%
% <<../svdpi_ProgSWGenerator1_1.png>>
%
% Note that the plot shows the output signal that was programmed to behave
% as follows:
%
% * Clock cycles<100: on=1,off=1
% * 100<Clock cycles<250: on=2,off=1
% * 250<Clock cycles: on=1,off=2

%% Generate the DPI component using DPIGEN command
% Using DPIGEN, generate the DPI component.
%
% Execute the DPIGEN command in MATLAB as follows:
%
%   dpigen -testbench ProgSWGenerator_tb ProgSWGenerator -args {0,0} 
%
% The following directory structure is generated:
%
% <<../svdpi_ProgSWGenerator3.png>>
%
% dpi_tb: Folder where all the testbench related files are.
%
% ProgSWGenerator_dpi.sv: Generated DPI component.
%
% ProgSWGenerator_dpi_pkg.sv: Generated SystemVerilog package.
%
% libProgSWGenerator_dpi.dll: Library containing the definitions of all
% imported functions.
%
% Note: DPIGEN will automatically try to compile the library. In order to
% just generate the files without compiling you should use the -c option.
% For example:
%
%   dpigen -c -testbench ProgSWGenerator_tb  ProgSWGenerator -args {0,0} 
%
%
%% Run Generated Testbench in HDL Simulator
%
% For ModelSim/QuestaSim, perform the following steps:
%
% * Start ModelSim/QuestaSim in GUI mode.
% * In the HDL Simulator,Change your current directory to "dpi_tb" under the code generation
% directory.
% * Enter the following command to start your simulation
%
%   do  run_tb_mq.do
%
% For example:
%
% <<../svdpi_ProgSWGenerator4.png>>
%
% The following wave form are generated:
%
% <<../svdpi_ProgSWGenerator5.png>>
%
% Note that the output wave (the bottom one) behaves in exactly the
% same way as the signal the was plotted in the MATLAB testbench.
%
% For Incisive and VCS simulator:
%
% * Start your terminal shell
% * Change the current directory to "dpi_tb" under the code generation
% directory
% * For Incisive enter the following command in your shell.
%  
%   sh run_tb_incisive.sh
%
% * For VCS enter the following command in your shell.
%  
%   sh run_tb_vcs.sh
% 
%
% * When the simulation finishes, you should see the following text printed
% in your console:
%
%  **************TEST COMPLETED (PASSED)**************
%
% This ends the Getting Started with MATLAB based SystemVerilog DPI
% Component Generation example.
