%% Hardware Design Patterns Using the MATLAB Function Block
% This example shows how to effectively use the MATLAB Function block to 
% model commonly used hardware algorithms using HDL Coder(TM). An 
% HDL design patterns library is used to show the features of MATLAB Coder 
% supported by HDL Coder.

% Copyright 2006-2020 The MathWorks, Inc.
      
%% Quick Introduction
% The MATLAB Function block supports simulation and code generation for a
% restricted subset of MATLAB(R) language. It provides a mechanism for
% algorithm implementation in Simulink(R) and Stateflow(R). To get more 
% information  on how to use this block in Simulink type:
%
%    >> docsearch('About Code Generation from MATLAB Algorithms')   

%% Subset of Features Supported by HDL Coder
% HDL Coder supports a powerful subset of MATLAB Function block
% features well suited for HDL implementations of various DSP and
% telecommunication applications such as sequence detectors, pattern generators,
% encoders, decoders etc., The following list briefly shows the features
% supported by MATLAB Function block in HDL Coder:
%
% * Various Numeric Classes (int,uint,logical,single,double)
% * Fixed-point arithmetic using 'fi' object
% * Arithmetic, Logical, Relational and Bitwise operator support
% * Full MATLAB expression support using above operators
% * 1-D and 2-D Matrix Operations
% * Matrix Subscripting
% * Control flow using if, switch, for statements
% * Sub functions
% * Persistent variables to model state
% * Fixed point and integer MATLAB library functions

%% Modeling Hardware Algorithms
% The MATLAB Function block provides a mechanism to model at a high level of 
% abstraction with a concise and textual way of expressing behavior 
% of a hardware algorithm. HDL Coder provides an easy path 
% to implementation from such an algorithmic level representation.
% The following sections show how to use this block effectively in HDL Coder.

% To illustrate the use of the above features in hardware modeling a 
% sample patterns library is created that shows how to model common 
% HDL problems. To open this sample library model please type 
% at the command prompt

open_system('eml_hdl_design_patterns')

%% Using Blocks in this Library
% To build some sample models using blocks in this model and observe the 
% generated code please follow these steps:
%
% * Create a new model.
% * Copy the block of interest from the eml_hdl_design_patterns library to this model.
% * Place it in a subsystem or a device under test.
% * Run 'hdlsetup' command.
% * Run 'makehdl' to generate code for the block
% * Build valid test bench around it using Simulink sources and sinks.
% * Run 'makehdltb' command to generate testbench.
% * Use the Modelsim '.do' script file to simulate the generated code.
%
% see tutorial example model 'eml_hdl_incrementer' for more details or type
%
%    >> docsearch('Tutorial Example: Incrementer')

%% Modeling Arithmetic
% This section talks about some of the design considerations
% that help generate efficient HDL from the MATLAB Function
% block. Please note that for modeling arbitrary length arithmetic
% operations using signed and unsigned logic vectors use of fi object is
% recommended. The fi objects provide a powerful mechanism to model fixed
% point arithmetic. Here are a couple of things to note when using fi objects
% in the MATLAB Function block.
% 
% The fi function helps you to define a fixed-point object with customized 
% 'numerictype' (that defines sign, wordlength, fractionlength) and 
% 'fimath' (that defines rounding and saturation modes)
%
% For HDL code generation, we recommend the fimath shown below.
% (with 'Floor', 'Wrap' and 'FullPrecision' modes) as shown below.
%
% However when modeling algorithms requiring more complicated rounding
% and saturation logic you may use other fimath modes for 
% rounding (floor,ceil,fix,nearest) and overflow (wrap,saturate)
%
%
%    fimath(...
%    'RoundMode', 'floor',...
%    'OverflowMode', 'wrap',...
%    'ProductMode', 'FullPrecision', 'ProductWordLength', 32,...
%    'SumMode', 'FullPrecision', 'SumWordLength', 32);
%
% Examples:
%  The following examples show the affect of fimath properties on the
%  generated code.
%
%    open_system('eml_hdl_design_patterns/Adders/add_with_carry')
%    open_system('eml_hdl_design_patterns/Misc/eml_expr')
%

%% Modeling State Using Persistent Variables
% To model a complex control logic, the ability to model registers is a
% basic requirement. In the MATLAB Coder programming model, the state-holding
% elements are represented as persistent variables. A variable 
% declared persistent retains its value across function calls in software, 
% and across steps of Simulink sample times. State holding elements in 
% hardware like registers and flip-flops also exhibit similar behavior. 
% The following examples how the values of persistent variables can be changed 
% using global and local reset conditions.
%
%
% Examples:
%    open_system('eml_hdl_design_patterns/Delays')
%    open_system('eml_hdl_design_patterns/Delays/unit delay')
%    open_system('eml_hdl_design_patterns/Delays/integer delay')
%    open_system('eml_hdl_design_patterns/Delays/tap delay')
%    open_system('eml_hdl_design_patterns/Delays/tap delay vector')

%% Modeling Counters and FSMs
% The MATLAB Coder control-constructs such as switch/case and if-elseif-else,
% coupled with delay elements and fixed point arithmetic operations, let 
% you model control logic. The examples in FSMs show how to use the switch-case and
% the if-elseif-end control statements. The counter show to model state and how to
% quantize data elements within loops.
%
% Examples:
%    open_system('eml_hdl_design_patterns/FSMs')
%    open_system('eml_hdl_design_patterns/Counters')


%% Modeling Bitwise Operations
% The MATLAB Function block supports a variety of bitwise operations
% useful for hardware bit manipulation operations like bit
% concatenation, bit packing and unpacking, conversions between integer and
% bits, and pn-sequence generation and bit-scramblers. 
%
% Here is a quick list of bitwise functions that are supported
% by HDL Coder:
%
% * bitget, bitsliceget, bitconcat, bitset, bitcmp
% * bitand, bitor, bitxor
% * bitandreduce, bitorreduce, bitxorreduce
% * bitshift, bitsll, bitsrl, bitsra, bitrol, bitror
%
% When modeling pure logic and no math operations in the MATLAB Function block
% the following settings on input operands are recommended.
%
% * Prefer unsigned to signed input operands 
% * Use non saturating fimath options to generate less hardware.
% * Prefer 'OverflowMode' to be 'wrap' and 'RoundMode' to be 'floor'
%
% Examples:
%    open_system('eml_hdl_design_patterns/Bit Twiddlers/hdl_bit_ops')
%    open_system('eml_hdl_design_patterns/Bit Twiddlers/signal_distance')
%    open_system('eml_hdl_design_patterns/Word Twiddlers/nibble_swap_with_slice_concat')
%
% For an example that shows how to perform a conversion between integer and
% bits, open the model |hdlcoder_int2bits_bits2int|.
%
%   open_system('hdlcoder_int2bits_bits2int')
%
% This model uses a MATLAB Function block that is implemented in the |Word
% Twiddlers| library.
%
%   open_system('eml_hdl_design_patterns/Word Twiddlers/Bits2Int')
%   open_system('eml_hdl_design_patterns/Word Twiddlers/Int2Bits')
%   open_system('eml_hdl_design_patterns/Word Twiddlers/Integer to Bits')
%   open_system('eml_hdl_design_patterns/Word Twiddlers/Bits to Integer')
%
%% Modeling Hardware Elements
% The MATLAB Function block can be used to model various hardware elements like
% barrel shifters, rotators, carry save adders using simple and concise MATLAB scripts. 
%
% Examples:
% open_system('eml_hdl_design_patterns/Shift Registers/shift_reg_universal')

%% Conclusion
% This example illustrates various opportunities that open up for
% hardware modeling through the use of the MATLAB Function block. A set of
% patterns to solve common hardware modeling problems using the MATLAB Function
% block are discussed. Please read the doc for more information on this 
% library .
%
%    >> docsearch('The eml_hdl_design_patterns Library')


displayEndOfDemoMessage(mfilename)
