Resolve Index Errors During Simulation

Issue

If you use a simulation tool to verify HDL code generated from a MATLAB^® algorithm or a Simulink^® model that uses a MATLAB Function block, the array indices may not always be resolved and may often be 0. MATLAB displays this error in the Command Window.

Simulation failed. See report.

The error originates from an error in the simulator. This error can take the form:

# ** Fatal: (vsim-3421) Value -1 is out of range 0 to 16383.

Possible Solutions

The error may occur during simulation when the simulator executes an index operation while propagating signals. Because the simulator is propagating signals, indices may be unresolved. Consequently, when the simulator performs a subtraction operation on an unresolved index and then accesses an array with an out-of-bounds index, the simulator generates index errors.

To resolve the error, try one of these solutions:

Follow the indexing best practices for MATLAB code for HDL code generation to minimize automatic index conversions. For more information, see Optimize Indexing When Verifying Code with Simulation Tools. If you optimize the indexing in your MATLAB algorithm or MATLAB code in the MATLAB Function block, it can result in fewer index errors during simulation.
Enable the Suppress out of bounds access errors by generating simulation-only index checks configuration parameter during HDL code generation. For more information, see Use SimIndexCheck to Suppress Index Errors.

Optimize Indexing When Verifying Code with Simulation Tools

Optimize the indexing in your MATLAB algorithm or MATLAB code in the MATLAB Function block. For more information, see Indexing Best Practices for HDL Code Generation.

For example, this MATLAB algorithm enhances the contrast of images by transforming the values in an intensity image so that the histogram of the output image is approximately flat. For more information on this algorithm, see Image Enhancement by Histogram Equalization. To illustrate this issue, simulate the HDL code of the unoptimized and optimized algorithms and compare the results.

Unoptimized MATLAB Algorithm	Optimized MATLAB Algorithm
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % mlhdlc_heq.m % Histogram Equalization Algorithm %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% function [x_out, y_out, pixel_out] = ... mlhdlc_heq(x_in, y_in, pixel_in, width, height) % Copyright 2011-2024 The MathWorks, Inc. persistent histogram persistent transferFunc persistent histInd persistent cumSum if isempty(histogram) histogram = zeros(1, 2^14); transferFunc = zeros(1, 2^14); histInd = 0; cumSum = 0; end % Figure out indexes based on where we are in the frame if y_in < height && x_in < width % valid pixel data histInd = pixel_in + 1; elseif y_in == height && x_in == 0 % first column of height+1 histInd = 1; elseif y_in >= height % vertical blanking period histInd = min(histInd + 1, 2^14); elseif y_in < height % horizontal blanking - do nothing histInd = 1; end % Read histogram (must be outside conditional logic) histValRead = histogram(histInd); % Read transfer function (must be outside conditional logic) transValRead = transferFunc(histInd); % If valid part of frame add one to pixel bin % and keep transfer func val if y_in < height && x_in < width histValWrite = histValRead + 1; % Add pixel to bin transValWrite = transValRead; % Write back same value cumSum = 0; elseif y_in >= height % In blanking time index through all bins and reset to zero histValWrite = 0; transValWrite = cumSum + histValRead; cumSum = transValWrite; else histValWrite = histValRead; transValWrite = transValRead; end % Write histogram (must be outside conditional logic) histogram(histInd) = histValWrite; % Write transfer function (must be outside conditional logic) transferFunc(histInd) = transValWrite; pixel_out = transValRead; x_out = x_in; y_out = y_in;	%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% % mlhdlc_heq_bp.m % Histogram Equalization Algorithm %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% function [x_out, y_out, pixel_out] = ... mlhdlc_heq_bp(x_in, y_in, pixel_in, width, height) % Copyright 2011-2024 The MathWorks, Inc. persistent histogram persistent transferFunc persistent histInd persistent cumSum if isempty(histogram) histogram = zeros(1, 2^14); transferFunc = zeros(1, 2^14); histInd = 0; cumSum = 0; end % Adjust histInd index variable to be 0-based if y_in < height && x_in < width histInd = pixel_in; elseif y_in == height && x_in == 0 histInd = 0; elseif y_in >= height histInd = min(histInd + 1, 2^14-1); elseif y_in < height histInd = 0; end % Add 1 to the value of the 0-based histInd when indexing histValRead = histogram(histInd+1); % Add 1 to the value of the 0-based histInd when indexing transValRead = transferFunc(histInd+1); if y_in < height && x_in < width histValWrite = histValRead + 1; transValWrite = transValRead; cumSum = 0; elseif y_in >= height histValWrite = 0; transValWrite = cumSum + histValRead; cumSum = transValWrite; else histValWrite = histValRead; transValWrite = transValRead; end % Add 1 to the value of the 0-based histInd when indexing histogram(histInd+1) = histValWrite; % Add 1 to the value of the 0-based histInd when indexing transferFunc(histInd+1) = transValWrite; pixel_out = transValRead; x_out = x_in; y_out = y_in;

Unoptimized MATLAB Algorithm

Optimized MATLAB Algorithm

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% mlhdlc_heq.m
% Histogram Equalization Algorithm
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
function [x_out, y_out, pixel_out] = ...
    mlhdlc_heq(x_in, y_in, pixel_in, width, height)

% Copyright 2011-2024 The MathWorks, Inc.

persistent histogram
persistent transferFunc
persistent histInd
persistent cumSum

if isempty(histogram)
    histogram = zeros(1, 2^14);
    transferFunc = zeros(1, 2^14);
    histInd = 0;
    cumSum = 0;
end

% Figure out indexes based on where we are in the frame
if y_in < height && x_in < width % valid pixel data
    histInd = pixel_in + 1;
elseif y_in == height && x_in == 0 % first column of height+1
    histInd = 1;
elseif y_in >= height % vertical blanking period
    histInd = min(histInd + 1, 2^14);
elseif y_in < height % horizontal blanking - do nothing
    histInd = 1;
end

% Read histogram (must be outside conditional logic)
histValRead = histogram(histInd);

% Read transfer function (must be outside conditional logic)
transValRead = transferFunc(histInd);

% If valid part of frame add one to pixel bin 
% and keep transfer func val
if y_in < height && x_in < width
    histValWrite = histValRead + 1; % Add pixel to bin
    transValWrite = transValRead; % Write back same value
    cumSum = 0;
elseif y_in >= height % In blanking time index through all bins and reset to zero
    histValWrite = 0;
    transValWrite = cumSum + histValRead;
    cumSum = transValWrite;
else
    histValWrite = histValRead;
    transValWrite = transValRead;
end

% Write histogram (must be outside conditional logic)
histogram(histInd) = histValWrite;

% Write transfer function (must be outside conditional logic)
transferFunc(histInd) = transValWrite;

pixel_out = transValRead;
x_out = x_in;
y_out = y_in;

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% mlhdlc_heq_bp.m
% Histogram Equalization Algorithm
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
function [x_out, y_out, pixel_out] = ...
    mlhdlc_heq_bp(x_in, y_in, pixel_in, width, height)

% Copyright 2011-2024 The MathWorks, Inc.

persistent histogram
persistent transferFunc
persistent histInd
persistent cumSum

if isempty(histogram)
    histogram = zeros(1, 2^14);
    transferFunc = zeros(1, 2^14);
    histInd = 0;
    cumSum = 0;
end

% Adjust histInd index variable to be 0-based
if y_in < height && x_in < width
    histInd = pixel_in;
elseif y_in == height && x_in == 0
    histInd = 0;
elseif y_in >= height
    histInd = min(histInd + 1, 2^14-1);
elseif y_in < height
    histInd = 0;
end

% Add 1 to the value of the 0-based histInd when indexing 
histValRead = histogram(histInd+1);

% Add 1 to the value of the 0-based histInd when indexing
transValRead = transferFunc(histInd+1);

if y_in < height && x_in < width
    histValWrite = histValRead + 1;
    transValWrite = transValRead;
    cumSum = 0;
elseif y_in >= height
    histValWrite = 0;
    transValWrite = cumSum + histValRead;
    cumSum = transValWrite;
else
    histValWrite = histValRead;
    transValWrite = transValRead;
end

% Add 1 to the value of the 0-based histInd when indexing
histogram(histInd+1) = histValWrite;

% Add 1 to the value of the 0-based histInd when indexing
transferFunc(histInd+1) = transValWrite;

pixel_out = transValRead;
x_out = x_in;
y_out = y_in;

Run the command mlhdlc_demo_setup('heq') in the MATLAB Command Window. This command copies the files mlhdlc_heq.m and mlhdlc_heq_tb.m into a temporary working folder.
Create a new MATLAB function in the temporary working folder named mlhdlc_heq_bp.m. Copy the optimized MATLAB algorithm from the table into the function.
Create a new MATLAB script in the temporary working folder named mlhdlc_heq_bp_tb.m. Copy the contents of the mlhdlc_heq_tb.m testbench into mlhdlc_heq_bp_tb.m. Change the line with the function call mlhdlc_heq to mlhdlc_heq_bp in order for the mlhdlc_heq_bp_tb.m testbench to exercise the function design of the optimized MATLAB algorithm, mlhdlc_heq_bp.

Generate and simulate the HDL code from the unoptimized MATLAB algorithm, mlhdlc_heq. Set the fixptcfg and hdlcfg object parameters and run the codegen command:

fixptcfg = coder.config('fixpt');
fixptcfg.TestBenchName = 'mlhdlc_heq_tb';

hdlcfg = coder.config('hdl');
hdlcfg.TestBenchName = 'mlhdlc_heq_tb';
hdlcfg.MapPersistentVarsToRAM = 0;
hdlcfg.TargetLanguage = 'VHDL';

hdlcfg.GenerateHDLTestBench = true;
hdlcfg.SimulateGeneratedCode = true;
hdlcfg.SimulationTool = 'ModelSim';

codegen -float2fixed fixptcfg -config hdlcfg mlhdlc_heq

Alternatively, you can use the MATLAB HDL Workflow Advisor. For more information, see Verify Code with HDL Test Bench.

Note the error in the MATLAB Command Window.

### Simulating the design 'mlhdlc_heq_fixpt' using 'ModelSim'.
### Generating Compilation Report mlhdlc_heq_fixpt_vsim_log_compile.txt
### Generating Simulation Report mlhdlc_heq_fixpt_vsim_log_sim.txt
Error occurred when running post codegeneration tasks
### Generating HDL Conformance Report mlhdlc_heq_fixpt_hdl_conformance_report.html.
### HDL Conformance check complete with 1 errors, 0 warnings, and 0 messages.
### Coder:hdl:post_codegen: Error: failed to run post code generation tasks:
Coder:FXPCONV:SimulationFailure Simulation failed. See report.

The error originates from an error in the simulator, in this instance ModelSim^®. In the MATLAB Command Window, click mlhdlc_heq_fixpt_vsim_log_sim.txt to view the simulation report. Note the error from the simulator.

# ** Fatal: (vsim-3421) Value -1 is out of range 0 to 16383.

Generate and simulate the HDL code from the optimized MATLAB algorithm, mlhdlc_heq_bp. Set the fixptcfg and hdlcfg object parameters and run the codegen command:

fixptcfg = coder.config('fixpt');
fixptcfg.TestBenchName = 'mlhdlc_heq_bp_tb';

hdlcfg = coder.config('hdl');
hdlcfg.TestBenchName = 'mlhdlc_heq_bp_tb';
hdlcfg.MapPersistentVarsToRAM = 0;
hdlcfg.TargetLanguage = 'VHDL';

hdlcfg.GenerateHDLTestBench = true;
hdlcfg.SimulateGeneratedCode = true;
hdlcfg.SimulationTool = 'ModelSim';

codegen -float2fixed fixptcfg -config hdlcfg mlhdlc_heq_bp

The code simulates without error.

### Simulating the design 'mlhdlc_heq_bp_fixpt' using 'ModelSim'.
### Generating Compilation Report mlhdlc_heq_bp_fixpt_vsim_log_compile.txt
### Generating Simulation Report mlhdlc_heq_bp_fixpt_vsim_log_sim.txt
### Simulation successful.

Use `SimIndexCheck` to Suppress Index Errors

HDL Coder™ may not optimize all instances of index conversions. If the index simulation error persists, you can use the Suppress out of bounds access errors by generating simulation-only index checks configuration parameter during HDL code generation. If you enable this parameter, HDL Coder generates additional logic that runs when you simulate your HDL code to prevent array indices from going out of bounds. Enabling this parameter disables all index checking during simulation.