Modifying the Filter to Use Streaming

On this page…
What Is Streaming? Why Use Streaming? Modifying Your M-Code How to Generate C Code for Your Modified M-Code How to Test Your MEX Function

What Is Streaming?

A streaming filter is called repeatedly to process fixed-size chunks of input data, or frames, until it has processed the entire input signal. The frame size can be as small as a single sample, in which case the filter would be operating in a sample-based mode, or up to a few thousand samples, for frame-based processing.

Back to Top

Why Use Streaming?

The design of the filter algorithm in Modifying the Filter to Accept a Variable Length Signal has the following disadvantages:

• The algorithm does not use memory efficiently.

  Preallocating a fixed amount of memory for each input signal for the lifetime of the program means more memory is allocated than is in use.

• You must know the size of the input signal at the time you call the function. If the input signal is arriving in real time or as a stream of samples, you would have to wait to accumulate the entire signal before you could pass it, as a batch, to the filter.

• The signal size is limited to a maximum size.

In an embedded application, the filter is likely to be processing a continuous input stream. As a result, the input signal may be substantially longer than the maximum length that a filter working in batch mode could possibly handle. To make the filter work for any signal length, it must run in real time. One solution is to convert the filter from batch-based processing to stream-based processing.

Back to Top

Modifying Your M-Code

The conversion to streaming involves:

• Introducing a first-in, first-out (FIFO) queue.

  The FIFO queue acts as a temporary storage buffer, which holds a small number of samples from the input data stream. The number of samples held by the FIFO queue must be exactly the same as the number of samples in the filter's impulse response, so that the function can perform the convolution operation between the filter coefficients and the input signal.

• Making the FIFO queue and the filter weights persistent.

  The filter is called repeatedly until it has processed the entire input signal. Therefore, the FIFO queue and filter weights need to persist so that the adaptation process does not have to start over again after each subsequent call to the function.

The modified filter code is in emldemo_lms_04.m. The changes to the code are in bold:

function [ signal_out, err, weights_out ] = ...
  emldemo_lms_04(distorted, desired)            %#eml
    
  persistent weights;
  persistent fifo;

  % Filter length:
  L = uint32(32);

  % Adaptation step size:
  mu = 4/(32*1024);

  % Signal length:
  N = length(distorted);
    
  if length(desired) == N 
    if isempty(weights)
      % Filter coefficients:
      weights = zeros(L,1);
      % FIFO Shift Register:
      fifo = zeros(L,1);
    end
        
    % Pre-allocate output and error signals:
    signal_out = zeros(N,1);
    err = zeros(N,1);
                
    % Filter Update Loop:
    for n = 1:N
      fifo(1:L-1) = fifo(2:L);
      fifo(L) = distorted(n);
      signal_out(n) = weights' * fifo;
      err(n) = desired(n) - signal_out(n) ;
      weights = weights + mu*err(n)*fifo;
    end
        
    % Output the filter weights:
    weights_out = weights;
  else
    error('Lengths of input signals are not equal');
  end
end

Summary of Changes to the Filter Algorithm

Note the following important changes to the filter algorithm:

• N is no longer an input parameter.

• The filter weights and the FIFO queue are declared as persistent:

  persistent weights;
  persistent fifo;

• The FIFO queue is initialized:

  fifo = zeros(L,1);

• The FIFO queue is used in the filter update loop:

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

• You cannot output a persistent variable, therefore a new variable weights_out is used to output the filter weights:

  function [ signal_out, err, weights_out ] = ...
    emldemo_lms_04(distorted, desired)

  weights_out = weights;

Back to Top

How to Generate C Code for Your Modified M-Code

Follow the same procedure you used in Generating C Code to generate a MEX function and a C library file. To run the build scripts, enter emldemo_lms_build_04_mex and then emldemo_lms_build_04_lib at the MATLAB prompt.

Summary of Changes to the Build Scripts

The build files contain a new parameter N, which sets up the frame size. In this case, the build script uses a value of N=2048 samples per frame for the frame size.

Back to Top

How to Test Your MEX Function

Follow the same procedure you used in Using the Test Script with the file emldemo_lms_test_04. The test outputs show that the modified filter is performing in exactly the same way as the original filter. The modifications for converting the filter from batch-based processing to stream-based processing generate Embedded MATLAB compliant code that is functionally identical to the original M-code.

Summary of Changes to the Test Script

Note the following changes to the test script:

• You must now specify the frame size and calculate the number of frames in your audio sample:

  % Frame size:
  FrameSize = 2048;
  % Number of frames
  NumFrames = ceil(N/FrameSize);
  

• For test purposes, you must zero pad the input signals so that the number of samples is an integer multiple of the frame size.

  % Zero-pad:
  whiteNoise = [ whiteNoise ; zeros(FrameSize*NumFrames - N,1) ];
  distorted = [ distorted  ; zeros(FrameSize*NumFrames - N,1) ];
  

• When you test the modified algorithm, you call it repeatedly (using a for- loop) until it has processed the entire input signal:

  % Algorithm under test:
  for n = 0:NumFrames-1
    indexRange = n*FrameSize+1:(n+1)*FrameSize;
    [ yt et test.impulse ] = ...
      emldemo_lms_04_mex(whiteNoise(indexRange), ...
        distorted(indexRange));
    test.signal(indexRange) = yt;
    test.error(indexRange) = et;
  end
  

Testing the Function with Other Audio Signals

Because the filter operates in a stream-based mode, it can process any audio signal regardless of the number of samples the signal contains. You can modify emldemo_lms_test_04.m to load a different audio file such as laughter.mat (on the MATLAB path) instead of handel.mat. MATLAB includes a total of six audio files that you can use as examples to test the LMS function. To see the complete list, use the following command at the MATLAB command line:

ls ([matlabroot '\toolbox\matlab\audiovideo\*.mat'])

Back to Top

Modifying the Filter to Accept a Variable Length Signal

Adding Adapt and Reset Controls

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