Making the LMS Filter Code Embedded MATLAB Compliant :: Making Your M-Code Compliant with the Embedded MATLAB Subset (Embedded MATLAB™)

Making the LMS Filter Code Embedded MATLAB Compliant

On this page…
Copying Files Locally Setting Up Your C Compiler Compiling M-Code Using emlmex Next Task See Also

On this page…

Copying Files Locally

Setting Up Your C Compiler

Compiling M-Code Using emlmex

Next Task

Copying Files Locally

Copy the tutorial files to a local folder:

Change to the matlabroot/toolbox/eml/ folder. At the MATLAB command line, enter:
```
cd([matlabroot '/toolbox/eml'])
```
Create the local destination folder, for example, c:/eml/tutorial.
Copy the tutorial subfolder and its contents to your local folder by typing:
```
copyfile('tutorial', 'destination')
```

You are now ready to set up your C compiler.

Setting Up Your C Compiler

Before using emlmex to compile the LMS Filter example code, you must set up your C compiler. To set up the default C compiler supplied with MATLAB:

At the MATLAB command line, enter:

mex -setup

The MATLAB output is:

Please choose your compiler for building external 
interface (MEX) files: 
 
Would you like mex to locate installed compilers [y]/n?

Enter y to see the list of installed compilers.
MATLAB outputs a list of installed compilers. (The list of compilers shown in your version of MATLAB may be different from the list shown in this example.)
```
Select a compiler: 
[1] Lcc-win32 C 2.4.1 in C:\PROGRA~1\MATLAB\R2008b\sys\lcc 
 
[0] None 
 
Compiler:
```

Enter 1 to select the default compiler.

MATLAB outputs:

Please verify your choices: 
 
Compiler: Lcc-win32 C 2.4.1 
Location: C:\PROGRA~1\MATLAB\R2008b\sys\lcc 
 
Are these correct [y]/n?

Enter y to verify your choice.
The MATLAB output is:
```
Done . . . 
```
You have successfully set up the C compiler.

See Setting Up the C Compiler in the Embedded MATLAB User's Guide for more information.

Compiling M-Code Using emlmex

You are now ready to compile your code using emlmex, which checks M-code for compliance with Embedded MATLAB syntax and semantics, as described in Working with the Embedded MATLAB Subset. After successful compilation, emlmex generates a MEX function that you can test in MATLAB.

To begin the process of making your M-code compliant with the Embedded MATLAB subset, you work with the file emldemo_lms_01.m.

To compile the LMS Filter code my_emldemo_lms_01.m:

Set your MATLAB current folder to the folder that contains your files for this tutorial. At the MATLAB command line, enter:
```
cd folder
```
where folder is the full path name of the folder containing your files. See Viewing and Changing the Current Folder Using the Current Folder Browser in the MATLAB Desktop Tools and Development Environment documentation for more information.
Open emldemo_lms_01.m in the MATLAB Editor. At the MATLAB command line, type:
```
edit emldemo_lms_01.m
```
The M-Lint message indicator in the top right corner of the MATLAB Editor is green, which indicates that M-Lint has not detected any errors, warnings, or opportunities for improvement in the code.
Turn on Embedded MATLAB error checking by adding the %#eml compilation directive after the function declaration.
```
function [ signal_out, err, weights ] = ...
  emldemo_lms_01(distorted, desired, L)  %#eml
```
The M-Lint message indicator remains green indicating that M-Lint has not detected any Embedded MATLAB related issues. For more information on using M-Lint, see Checking M-File Code for Problems Using the M-Lint Code Analyzer in the MATLAB Desktop Tools and Development documentation.

Save the file in the current folder as my_emldemo_lms_01.m:

To match the function name to the file name, change the function name to my_emldemo_lms_01.
The function signature now looks like this:
```
function [ signal_out, err, weights ] = ...
  my_emldemo_lms_01(distorted, desired, L)
```
In the MATLAB Editor, select Save As from the File menu.

Enter my_emldemo_lms_01.m as the new file name.

Note If you do not match the filename to the function name, M-Lint warns you that these names are not the same and highlights the function name in orange to indicate that it can provide an automatic fix. For more information, see Making Changes Based on M-Lint Messages in the MATLAB documentation.

Click Save.

Now you are ready to compile the LMS Filter example code using emlmex.

Best Practice — Preserving Your Code

Because C uses static typing, emlmex must determine the properties of all variables in the M-files at compile time. Therefore, you must specify the properties of all function inputs at the same time as you compile the M-file with emlmex. To compile my_emldemo_lms_01.m you need to know the length of the audio signal that you are filtering.
To find the length of the audio sample handel.mat:
1. Load the music sample stored in the file handel.mat, which is on the MATLAB path. At the MATLAB command line, enter:
```
data = load('handel.mat')
```
  The MATLAB output is:
```
data = 
  y: [73113x1 double]
  Fs: 8192
```
  data.y is a vector containing the discrete time samples of the audio signal.data.Fs contains the sampling rate in samples per second
2. Set the length of the audio sample, N, to the length of the handel.mat audio signal. At the MATLAB command line, enter:
```
N = length(data.y)
```
  The MATLAB output is:
```
N = 73113
```
3. Compile the file my_emldemo_lms_01.m using emlmex. At the MATLAB command line, enter:
```
emlmex my_emldemo_lms_01 -eg { zeros(N,1) zeros(N,1) 32 } ...
  -o my_emldemo_lms_01_mex
```
  emlmex reports the following error, which includes a link to the offending line of code and a link to an error report:
```
??? Dimension 1 is fixed on the left-hand side but varies on
the right ([73113 x 1] ~= [:? x 1]). See documentation for
details.
Error in ==> my_emldemo_lms_01 Line: 49 Column: 9
C-MEX generation failed: Open error report.
??? Error using ==> emlmex
```
  The -eg option instructs emlmex to compile the file my_emldemo_lms_01.m using the sample input parameters {zeros(N,1) zeros(N,1) 32}. The -o option instructs emlmex to generate the MEX function in a file named my_emldemo_lms_01_mex, instead of the default, which is the same as the original M-code source file.
  Best Practice — Using the -eg Option to Specify Input Properties
  
  Use the -eg option to specify the input properties by example. emlmex extracts the data types and sizes of the variables listed in the cell array following the -eg option. It is important to understand that it is not the values of the variables that you are specifying with the -eg option, but the data types and array dimensions of these parameters. The -eg option is easy to use, does not alter your M-code, and is designed for prototyping a function that has a small number of primary inputs. Alternatively, you can use the assert function to define properties of primary function inputs directly in your M-file. See -eg Specify Input Parameters by Example for more information.
  
  Best Practice — Specifying an Output File Name
  
  Use the -o option to specify an output file name for the generated MEX function that is different from the name of the original M-file so that you can test the M-code and MEX function and compare the results. See -o Specify Output File Name for more information. If you do not specify an output file name, emlmex gives the MEX file the same name as the M-file. It assigns a new default platform-specific file extension to the MEX file, for example, .mexw32 for 32-bit Windows. (See Naming Conventions in the Embedded MATLAB User's Guide for more information.) If you subsequently refer to this file by its name only (without the extension), MATLAB selects the MEX file in accordance with file precedence rules. See File Precedence in MATLAB Programming Fundamentals.
  
  More About Error Reports
  
  You can also view errors by clicking the Open error report link. The error report provides a complete list of all the errors and warnings detected by emlmex. You must fix the first error in the list before addressing subsequent errors and warnings because many of these may be related to the first error. See Working with Compilation Reports in the Embedded MATLAB User's Guide for more information.
Click the my_emldemo_lms_01 Line:49 Column:9 link.
The my_emldemo_lms_01 file opens with the cursor at the offending line of code;
```
distorted = [ zeros(L-1,1); distorted ];
```
emlmex detects that you are changing the size of the array variable distorted after it has been defined. Because you have not specified that distorted is a variable-size array, you cannot change its size at run time.
Add the suffix _pad to the variable distorted on the left-hand side of the assignment statement to create a new variable distorted_pad, which contains the padded signal. This line of code becomes:
```
distorted_pad = [ zeros(L-1,1); distorted ];
```
The M-Lint message indicator turns orange to alert you that the file has at least one warning. M-Lint underlines the offending code in orange and places an orange marker to the right of it.
Move your pointer over the marker.
M-Lint detects that the value assigned to variable distorted_pad might never be used.
To address this warning, change the filter update loop to use the new variable distorted_pad instead of the original variable distorted. You need to make this change in two places: once each in the first and third lines inside the for-loop.
The filter update loop should now look like this:
```
for n = 1:N
  signal_out(n) = weights' * distorted_pad(n:n+L-1);
  err(n) = desired(n) - signal_out(n);
  weights = weights + mu*err(n)*distorted_pad(n:n+L-1);
end
```
The orange warning marker for this line of code disappears.
The M-Lint message indicator in the top right edge of the code turns green, which indicates that you have fixed all the errors and warnings detected by M-Lint.

Save the file and compile it again. At the MATLAB command line, enter:

emlmex my_emldemo_lms_01 -eg { zeros(N,1) zeros(N,1) 32 } ...
  -o my_emldemo_lms_01_mex

emlmex reports the following error, which includes a link to the offending line of code and a link to an error report:

??? Function 'figure' implicitly resolved in the MATLAB 
workspace.Implicit evaluation in MATLAB is not supported.
Please declare this function extrinsic using 
eml.extrinsic('figure'), or call it using feval.
Error in ==> my_emldemo_lms_01 Line: 63 Column: 9
C-MEX generation failed: Open error report.
??? Error using ==> emlmex

Click the my_emldemo_lms_01 Line: 63 Column: 9 link.
The my_emldemo_lms_01 file opens with the cursor at the offending line of code:
```
			 figure;
```
The Embedded MATLAB subset does not support the MATLAB function figure. When you call an unsupported MATLAB function, you must declare it to be extrinsic so MATLAB can execute it, but Embedded MATLAB does not try to generate code for it.
More About Extrinsic Functions

For more information on extrinsic functions, see Calling MATLAB Functions in the Embedded MATLAB User's Guide.
Alternatively, you can call the figure function using feval, see Calling MATLAB Functions Using feval in the Embedded MATLAB User's Guide for more information.

The functions stem , title, and num2str are also unsupported MATLAB functions. Declare all four functions extrinsic by adding the following declaration after the function signature:

% Declare extrinsic functions:
eml.extrinsic('figure','stem','title','num2str');

Your code should now look like this:

function [ signal_out, err, weights ] = ...
    my_emldemo_lms_01(distorted, desired, L)       %#eml

    % Declare extrinsic functions:
    eml.extrinsic('figure','stem','title','num2str');

    % Version Number:
    k = 1;
    
    % Adaptation step size:
    mu = 4/(32*1024);
    
    % Signal length:
    N = length(distorted);
    
    if length(desired) == N        
        
        % Filter coefficients:       
        weights = zeros(L,1);
        
        % Zero Pad Input Signal:
        distorted_pad = [ zeros(L-1,1); distorted ];
        
        % Pre-allocate output and error signals:
        signal_out = zeros(N,1);
        err = zeros(N,1);
                
        % Filter Update Loop:
        for n = 1:N
            signal_out(n) = weights' * distorted_pad(n:n+L-1);
            err(n) = desired(n) - signal_out(n) ;
            weights = weights + mu*err(n)*distorted_pad(n:n+L-1);
        end
        
        % Plot Impulse Response:
        figure;
        stem(weights);
        title(['LMS Filter -- Version #' num2str(k) ...
            ' -- Impulse Response']);
        
    else
        
        error('Lengths of input signals are not equal');
        
    end

end

Save the file and compile it again. At the MATLAB command line, enter:

emlmex my_emldemo_lms_01 -eg { zeros(N,1) zeros(N,1) 32 } ...
  -o my_emldemo_lms_01_mex

emlmex reports the following error. Note that the line number in your error report may not match the one shown here because you have modified the code.

??? Computed maximum size is not bounded. 
 Static memory allocation requires all sizes to be bounded. 
The computed size is [:? x 1]. 

Error in ==> my_emldemo_lms_01 Line: 47 Column: 19
C-MEX generation failed: Open error report.
??? Error using ==> emlmex

Click the my_emldemo_lms_01 Line:47 Column:19 link.

The my_emldemo_lms_01.m file opens with the cursor at the offending line of code:

weights = zeros(L,1);

The issue: you are using the input parameter L to define the size of the variable weights. Because you are using static array sizing, emlmex must be able to determine the size of all array variables at code generation time. Because the value of L is not known until run time, emlmex generates an error.

Note The LMS filter example in this tutorial uses static array sizing. However, the Embedded MATLAB subset supports variable-size arrays and matrices with known upper bounds. With this feature, you can define inputs, outputs, and local variables in Embedded MATLAB functions to represent data that varies in size at runtime. For more information, see Generating Code for Variable-Size Data in the Embedded MATLAB User's Guide.

To fix this error, set the filter length L to a constant value:
1. Remove the input parameter L.
  The function signature now looks like this:
```
function [ signal_out, err, weights ] = ...
  my_emldemo_lms_01(distorted, desired)
```
2. Set the size of the filter length at the start of the function after the function signature:
```
% Filter Length:
L = 32;
```

Save the file and compile my_emldemo_lms_01.m again, this time specifying only two input parameters:

emlmex my_emldemo_lms_01 -eg { zeros(N,1) zeros(N,1) } ...
  -o my_emldemo_lms_01_mex

emlmex reports the following error. Note that the line number in your error report may not match the one shown here because you have modified the code.

??? Size mismatch (size [32 x 1] ~= size [:? x 1]).
Mismatched varying and fixed sizes indicate a probable
run-time error. If this diagnostic is incorrect, use 
indexing to explicitly make the varying size fixed.
Error in ==> my_emldemo_lms_01 Line: 61 Column: 23
C-MEX generation failed: Open error report.
??? Error using ==> emlmex

Click the my_emldemo_lms_01 Line: 61 Column: 23 link.
The my_emldemo_lms_01 file opens with the cursor at the offending line of code:
```
weights = weights + mu*err(n)*distorted_pad(n:n+L-1);
```
emlmex cannot determine the size of the expression distorted_pad(n:n+L-1) because the values of both end points of the array index are variables.
Change the matrix index expression from (n:n+L-1) to (n+(0:L-1)) so that emlmex can determine the size of the expression.
```
weights = weights + mu*err(n)* distorted_pad(n+(0:L-1));
```
More About Matrix Indexing

For distorted_pad(n:n+L-1), the value of n and therefore the value of n+L-1 are variables so emlmex cannot determine the size of the expression n:n+L-1.
For distorted_pad(n+(0:L-1)), the lower and upper limits of the index array are known so emlmex can now determine the size of L elements of the matrix distorted_pad.
For more information, see Using Matrix Indexing Operations in the Embedded MATLAB User's Guide.

Make the same change for the line of code:

signal_out(n) = weights' * distorted_pad(n:n+L-1);

The filter update loop code should now look like this:

% Filter Update Loop:
for n = 1:N
  signal_out(n) = weights' * distorted_pad(n+(0:L-1));
  err(n) = desired(n) - signal_out(n) ;
  weights = weights + mu*err(n)*distorted_pad(n+(0:L-1));
end

Save the file as my_emldemo_lms_01_compliant.m:
1. To match the function name to the file name, change the function name to my_emldemo_lms_01_compliant.
2. In the MATLAB Editor, select Save As from the File menu.
3. Enter my_emldemo_lms_01_compliant.m as the new file name.
4. Click Save.
5. Close my_emldemo_lms_01_compliant.m.

Compile the file my_emldemo_lms_01_compliant.m:

emlmex my_emldemo_lms_01_compliant ...
  -eg { zeros(N,1) zeros(N,1) } ...
  -o my_emldemo_lms_01_compliant_mex

This time emlmex compiles the file without errors or warnings.

Next Task

The LMS Filter example code is now Embedded MATLAB compliant. You are ready to begin the next task in this tutorial, Testing Compliant Code in MATLAB.