Tutorial Example: Incrementer

On this page…

Example Model Overview Setting Up Creating the Model and Configuring General Model Settings Adding an Embedded MATLAB Function Block to the Model Setting Optimal Fixed-Point Options for the Embedded MATLAB Function Block Programming the Embedded MATLAB Function Block Constructing and Connecting the DUT_eML_Block Subsystem Compiling the Model and Displaying Port Data Types Simulating the eml_hdl_incrementer_tut Model Generating HDL Code

Example Model Overview

In this tutorial, you construct and configure a simple model, eml_hdl_incrementer_tut, and then generate VHDL code from the model. eml_hdl_incrementer_tut includes an Embedded MATLAB Function block that implements a simple fixed-point counter function, incrementer. The incrementer function is invoked once during each sample period of the model. The function maintains a persistent variable count, which is either incremented or reinitialized to a preset value (ctr_preset_val), depending on the value passed in to the ctr_preset input of the Embedded MATLAB Function block. The function returns the counter value (counter) at the output of the Embedded MATLAB Function block.

The Embedded MATLAB Function block is contained in a subsystem, DUT_eML_Block. The subsystem functions as the device under test (DUT) from which HDL code is generated. The following figure shows the subsystem.

The root-level model drives the subsystem and includes Display and To Workspace blocks for use in simulation. (The Display and To Workspace blocks do not generate any HDL code.) The following figure shows the model.

Tip   If you do not want to construct the model step by step, or do not have time, the example model is available in the demos directory as the following file: MATLABROOT\toolbox\hdlcoder\hdlcoderdemos\eml_hdl_incrementer.mdl After you open the model, save a copy of it to your local directory as eml_hdl_incrementer_tut.mdl.

The Incrementer Function Code

The following code listing gives the complete incrementer function definition:

function counter = incrementer(ctr_preset, ctr_preset_val)
% The function incrementer implements a preset counter that counts
% how many times this block is called. 
%
% This example function shows how to model memory with persistent variables,
% using fimath settings suitable for HDL. It also demonstrates MATLAB
% operators and other language features supported 
% for HDL code generation from Embedded MATLAB Function blocks.
%
% On the first call, the result 'counter' is initialized to zero.
% The result 'counter' saturates if called more than 2^14-1 times.
% If the input ctr_preset receives a nonzero value, the counter is 
% set to a preset value passed in to the ctr_preset_val input.

persistent current_count;
if isempty(current_count)
    % zero the counter on first call only
    current_count = uint32(0); 
end
           

counter = getfi(current_count);

if ctr_preset
    % set counter to preset value if input preset signal is nonzero
    counter = ctr_preset_val; 
else
    % otherwise count up
    inc = counter + getfi(1); 
    counter = getfi(inc);    
end

% store counter value for next iteration
current_count = uint32(counter);

function hdl_fi = getfi(val)

nt = numerictype(0,14,0);

fm = hdlfimath;
hdl_fi = fi(val, nt, fm);

Back to Top

Setting Up

Before you begin building the example model, set up a working directory for your model and generated code.

Setting Up a Directory

1. Start the MATLAB software.

2. Create a directory named eml_tut, for example:

   mkdir D:\work\eml_tut

   The eml_tut directory stores the model you create, and also contains directories and generated code. The location of the directory does not matter, except that it should not be within the MATLAB directory tree.

3. Make the eml_tut directory your working directory, for example:

   cd D:\work\eml_tut

Back to Top

Creating the Model and Configuring General Model Settings

In this section, you create a model and set some parameters to values recommended for HDL code generation, using the M-file utility, hdlsetup.m. The hdlsetup command uses the set_param function to set up models for HDL code generation quickly and consistently. See Initializing Model Parameters with hdlsetup for further information about hdlsetup.

To set the model parameters:

1. Create a new model.

2. Save the model as eml_hdl_incrementer_tut.mdl.

3. At the MATLAB command prompt, type:

   hdlsetup('eml_hdl_incrementer_tut')
   

4. Select Configuration Parameters from the Simulation menu in the eml_hdl_incrementer_tut model window.

   The Configuration Parameters dialog box opens with the Solver options pane displayed.

5. Set the following Solver options, which are useful in simulating this model:

   Fixed step size: 1

   Stop time: 5

6. Click Apply. Then close the Configuration Parameters dialog box.

7. Select Save from the Simulink File menu, to save the model with its new settings.

Back to Top

Adding an Embedded MATLAB Function Block to the Model

1. Open the Simulink Library Browser. Then, select the Simulink/User-Defined Functions sublibrary.

2. Select the Embedded MATLAB Function block from the library window and add it to the model.

   The model should now appear as shown on the following figure.

   

3. Change the block label from Embedded MATLAB Function to eml_inc_block.

   The model should now appear as shown on the following figure.

   

4. Save the model.

5. Close the Simulink Library Browser window.

Back to Top

Setting Optimal Fixed-Point Options for the Embedded MATLAB Function Block

This section describes how to set up the FIMATH specification and other fixed-point options that are recommended for efficient HDL code generation from the Embedded MATLAB Function block. The recommended settings are

• ProductMode property of the FIMATH specification: 'FullPrecision'

• SumMode property of the FIMATH specification: 'FullPrecision'

• Treat these inherited signal types as fi objects option: Fixed-point (This is the default setting.)

Configure the options as follows:

1. If it is not already open, open the eml_hdl_incrementer_tut model that you created in Adding an Embedded MATLAB Function Block to the Model.

2. Double-click the Embedded MATLAB Function block to open it for editing. The Embedded MATLAB Function block editor appears.

3. Select Edit Data/Ports from the Tools menu. The Ports and Data Manager dialog box opens, displaying the default FIMATH specification and other properties for the Embedded MATLAB Function block.

   

4. Select Specify Other. Selecting this option enables the Embdedded MATLAB Function block fimath text entry field..

5. The M-function hdlfimath.m is a utility that defines a FIMATH specification that is optimized for HDL code generation. Replace the default Embdedded MATLAB Function block fimath specification with a call to hdlfimath as follows:

   hdlfimath;

6. Click Apply. The Embedded MATLAB Function block properties should now appear as shown in the following figure.

   

7. Close the Ports and Data Manager dialog box.

8. Save the model.

Back to Top

Programming the Embedded MATLAB Function Block

The next step is add code to the Embedded MATLAB Function block to define the incrementer function, and then use diagnostics to check for errors.

To program the function:

1. If not already open, open the eml_hdl_incrementer_tut model that you created in Adding an Embedded MATLAB Function Block to the Model.

2. Double-click the Embedded MATLAB Function block to open it for editing. The Embedded MATLAB Editor appears. The editor displays a default function definition, as shown in the following figure.

   

   The next step is to replace the default function with the incrementer function.

3. Select Select All from the Edit menu of the Embedded MATLAB Editor. Then, delete all the default code.

4. Copy the complete incrementer function definition from the listing given in The Incrementer Function Code, and paste it into the editor.

   The Embedded MATLAB Editor should appear as shown in the following figure:

   

5. Select Save Model from the File menu in the Embedded MATLAB Editor.

   Saving the model updates the model window, redrawing the Embedded MATLAB Function block.

   Changing the function header of the Embedded MATLAB Function block makes the following changes to the Embedded MATLAB Function block in the model:

   • The function name in the middle of the block changes to incrementer

   • The arguments ctr_preset and ctr_preset_val appear as input ports to the block.

   • The return value counter appears as an output port from the block.

6. Resize the block to make the port labels more legible. The model should now resemble the following figure.

   

7. Save the model again.

Back to Top

Constructing and Connecting the DUT_eML_Block Subsystem

This section assumes that you have completed Programming the Embedded MATLAB Function Block with a successful build. In this section, you construct a subsystem containing the incrementer function block, to be used as the device under test (DUT) from which HDL code is generated. You then set the port data types and connect the subsystem ports to the model.

Constructing the DUT_eML_Block Subsystem

Construct a subsystem containing the incrementer function block as follows:

1. Click the incrementer function block.

2. From the Edit menu, select Create Subsystem.

   A subsystem, labeled Subsystem, is created in the model window.

3. Change the Subsystem label to DUT_eML_Block.

Setting Port Data Types for the Embedded MATLAB Function Block

1. Double-click the subsystem to view its interior. As shown in the following figure, the subsystem contains the incrementer function block, with input and output ports connected.

   

2. Double-click the incrementer function block, to open the Embedded MATLAB Editor. In the editor window, select Edit Data/Ports from the Tools menu. The Ports and Data Manager dialog box opens.

3. Select the ctr_preset entry in the port list on the left. Click the button labeled >> to display the Data Type Assistant. Set the Mode property for this port to Built in. Set the Data type property to boolean. Click the button labeled << to close the Data Type Assistant. Click Apply.

4. Select the ctr_preset_val entry in the port list on the left. Click the button labeled >> to display the Data Type Assistant. Set the Mode property for this port to Fixed point. Set the Signedness property for this port to Unsigned. Set the Word length property to 14. Click the button labeled << to close the Data Type Assistant. Click Apply.

5. Select the counter entry in the port list on the left. Click the button labeled >> to display the Data Type Assistant. Verify that the Mode property for this port is set to Inherit: Same as Simulink. Click the button labeled << to close the Data Type Assistant. Click Apply.

   The Ports and Data Manager dialog box should now appear as shown in the following figure.

   

6. Close the Ports and Data Manager dialog box and the editor.

7. Save the model and close the DUT_eML_Block subsystem.

Connecting Subsystem Ports to the Model

Next, connect the ports of the DUT_eML_Block subsystem to the model as follows:

1. From the Sources library, add a Constant block to the model. Set the value of the Constant to 1, and the Output data type mode to boolean. Change the block label to Preset.

2. Make a copy of the Preset Constant block. Set its value to 0, and change its block label to Increment.

3. From the Signal Routing library, add a Manual Switch block to the model. Change its label to Control. Connect its output to the In1 port of the DUT_eML_Block subsystem.

4. Connect the Preset Constant block to the upper input of the Control switch block. Connect the Increment Constant block to the lower input of the Control switch block.

5. Add a third Constant block to the model. Set the value of the Constant to 15, and the Output data type mode to Inherit via back propagation. Change the block label to Preset Value.

6. Connect the Preset Value constant block to the In2 port of the DUT_eML_Block subsystem.

7. From the Sinks library, add a Display block to the model. Connect it to the Out1 port of the DUT_eML_Block subsystem.

8. From the Sinks library, add a To Workspace block to the model. Route the output signal from the DUT_eML_Block subsystem to the To Workspace block.

9. Save the model.

Checking the Function for Errors

Use the built-in diagnostics of Embedded MATLAB Function blocks to test for syntax errors as follows:

1. If it is not already open, open the eml_hdl_incrementer_tut model.

2. Double-click the Embedded MATLAB Function block incrementer to open it for editing.

3. In the Embedded MATLAB Editor, select Build from the Tools menu (or press Ctrl+B) to compile and build the Embedded MATLAB Function block code.

The build process displays some progress messages. These messages will include some warnings, because the ports of the Embedded MATLAB Function block are not yet connected to any signals. You can ignore these warnings.

The build process builds a C-MEX S-function for use in simulation. The build process includes generation of C code for the S-function. The code generation messages you see during the build process refer to generation of C code, not to HDL code generation.

When the build concludes successfully, a message window appears.

If errors are found, the Diagnostics Manager window lists them. See Using the Embedded MATLAB Function Block for information on debugging Embedded MATLAB Function block build errors.

Back to Top

Compiling the Model and Displaying Port Data Types

In this section you enable the display of port data types and then compile the model. Model compilation verifies that the model structure and settings are correct, and update the model display.

1. From the Simulink Format menu, select Port/Signal Displays > Port Data Types.

2. From the Simulink Edit menu, select Update Diagram (or press Ctrl+D) to compile the model. This triggers a rebuild of the code. After the model compiles, the block diagram updates to show the port data types. The model should now appear as shown in the following figure.

   

3. Save the model.

Back to Top

Simulating the eml_hdl_incrementer_tut Model

Click the Start Simulation icon to run a simulation.

If necessary, the code rebuilds before the simulation starts.

After the simulation completes, the Display block shows the final output value returned by the incrementer function block. For example, given a Start time of 0, a Stop time of 5, and a zero value presented at the ctr_preset port, the simulation returns a value of 6, as shown in the following figure.

You may want to experiment with the results of toggling the Control switch, changing the Preset Value constant, and changing the total simulation time. You may also want to examine the workspace variable simout, which is bound to the To Workspace block.

Back to Top

Generating HDL Code

In this section, you select the DUT_eML_Block subsystem for HDL code generation, set basic code generation options, and then generate VHDL code for the subsystem.

Selecting the Subsystem for Code Generation

Select the DUT_eML_Block subsystem for code generation, as follows:

1. Open the Configuration Parameters dialog box. Click the HDL Coder category in the Select tree in the left pane of the dialog box.

2. Select eml_hdl_incrementer_tut/DUT_eML_Block from the Generate HDL for list.

3. Click Apply. The dialog box should now appear as shown in the following figure.

   

Generating VHDL Code

The top-level HDL Coder options should now be set as follows:

• The Generate HDL for field specifies the eml_hdl_incrementer_tut/DUT_eML_Block subsystem for code generation.

• The Language field specifies (by default) generation of VHDL code.

• The Folder field specifies (by default) that the code generation target directory is a subdirectory of your working directory, named hdlsrc.

Before generating code, select Current Folder from the Desktop menu in the MATLAB window. This displays the Current Directory browser, which lets you easily access your working directory and the files that are generated within it.

To generate code:

1. Click the Generate button.

   The coder compiles the model before generating code. Depending on model display options (such as port data types, etc.), the appearance of the model may change after code generation.

2. As code generation proceeds, the coder displays progress messages. The process should complete successfully with the message like the following:

   ### Starting HDL Check.
   ### HDL Check Complete with 0 errors, 0 warnings and 0 messages.
   
    
   
   ### Begin VHDL Code Generation
   ### Working on eml_hdl_incrementer/DUT_eML_Block as hdlsrc\DUT_eML_Block.vhd
   ### Working on eml_hdl_incrementer/DUT_eML_Block/eml_inc_blk as hdlsrc\eml_inc_blk.vhd
   Embedded MATLAB parsing for model "eml_hdl_incrementer"...Done
   Embedded MATLAB code generation for model "eml_hdl_incrementer"....Done
   ### HDL Code Generation Complete.
   

   Observe that the names of generated VHDL files in the progress messages are hyperlinked. After code generation completes, you can click these hyperlinks to view the files in the MATLAB Editor.

3. A folder icon for the hdlsrc directory is now visible in the Current Directory browser. To view generated code and script files, double-click the hdlsrc folder icon.

4. Observe that two VHDL files were generated. The structure of HDL code generated for Embedded MATLAB Function blocks is similar to the structure of code generated for Stateflow charts and Digital Filter blocks. The VHDL files that were generated in the hdlsrc directory are:

   • eml_inc_blk.vhd: VHDL code. This file contains entity and architecture code implementing the actual computations generated for the Embedded MATLAB Function block.

   • DUT_eML_Block.vhd: VHDL code. This file contains an entity definition and RTL architecture that provide a black box interface to the code generated in Embedded_MATLAB_Function.vhd.

   The structure of these code files is analogous to the structure of the model, in which the DUT_eML_Block subsystem provides an interface between the root model and the incrementer function in the Embedded MATLAB Function block.

   The other files that were generated in the hdlsrc directory are:

   • DUT_eML_Block_compile.do: Mentor Graphics ModelSim compilation script (vcom command) to compile the VHDL code in the two .vhd files.

   • DUT_eML_Block_synplify.tcl: Synplify synthesis script.

   • DUT_eML_Block_map.txt: Mapping file. This report file maps generated entities (or modules) to the subsystems that generated them (see Code Tracing Using the Mapping File).

5. To view the generated VHDL code in the MATLAB Editor, double-click the DUT_eML_Block.vhd or eml_inc_blk.vhd file icons in the Current Directory browser.

   At this point you should study the ENTITY and ARCHITECTURE definitions while referring to HDL Code Generation Defaults in the makehdl reference documentation. The reference documentation describes the default naming conventions and correspondences between the elements of a model (subsystems, ports, signals, etc.) and elements of generated HDL code.

Back to Top

Introduction

Useful Embedded MATLAB Function Block Design Patterns for HDL

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS