Using Matlab to debug software written for a digital signal

processor

Malcolm J. Goris
Netherlands Foundation for Research in Astronomy
Post Box 2
7990 AA Dwingeloo
The Netherlands
email: mgoris@nfra.nl
phone: +31 521 595 286
fax: +31 521 597 332

In Proceedings of Benelux Matlab Userconference

October 1997
Amsterdam, The Netherlands
Using Matlab to debug software written for a digital signal
processor
Malcolm J. Goris
Netherlands Foundation for Research in Astronomy
Post Box 2
7990 AA Dwingeloo
The Netherlands
email: mgoris@nfra.nl
phone: +31 521 595 286
fax: +31 521 597 332

Abstract
Digital signal processors (DSPs) are high-powered and highly-integrated processing
units that are used in computationally-intensive embedded-computing applications. Nor-
mal debugging tools are too low level to use for debugging the high-level functions that
DSPs are often programmed to do. However, a useful debugging environment may be cre-
ated by using Matlab to perform the same calculations as the DSP and verifying the DSP’s
results at suitable points in the software. The Matlab software can be easily written and it
provides a “truth” model for the results that should be obtained by the DSP. If the DSP’s
results differ from Matlab’s results then it is the DSP software that must be corrected.
In this paper, we describe how we used Matlab to debug an adaptive digital-beamforming
system. There was little overhead to the DSP to implement the debugging procedure,
allowing it to run in real time. We estimate that it sped our debugging and testing cycle
by a factor of six.

1 Introduction
Digital signal processors (DSPs) are typically used in embedded-computing applications that
require a fast CPU core that is optimized for signal processing tasks. They are used in ap-
plications such as mobile telephony, speech encoding and decoding and image processing and,
typically, perform tasks such as filtering, matrix manipulation, and transforms in real time. In
this paper we explain how normal debugging tools are insufficient to fully verify and correct
the operation of real-time DSP software. We give, as an example, an overview of a DSP-based
system that we developed and we show how we were able to fix high-level functions of the DSP
software using Matlab. The efficiency of using Matlab with respect to the normal debugging
tools was such that our debugging and testing cycle was sped by a factor of six.
To detect software bugs that were related to program design we used Matlab to verify that
the results of DSP functions were correct. An RS232 connection from the DSP to a PC was
used to communicate the input and output data of any function to and from Matlab via data
files. We created some simple Matlab scripts to read data from the files and used Matlab to
do the same computations that the DSP was doing on the same data. We were then able to
compare the results from the DSP with those from Matlab to verify whether the DSP software
was performing correctly. We could also make different calculations on the same data if we
needed to. The advantage of using Matlab in this way is that the complex functions under test
on the DSP can be written, often, in just one or two Matlab commands. This leaves very little
room for error in Matlab. And so, if the results given by Matlab were different to those of the
DSP’s then invariably the DSP software was at fault. Conversely, if Matlab’s and the DSP’s
results were the same then that was positive proof that the DSP software was correct because
the chance of getting the same results accidentally are negligible.
The remainder of this paper is structured as follows. In Section 2 we introduce the moti-
vation for using Matlab to debug DSP software. In Section 3 we briefly describe a real-time

1
system that we built and that uses a DSP for the main computing element. In Section 4 we
give, by way of a demonstration, the procedures we used to find and correct two software bugs
in our system. Section 5 concludes the paper.

2 Motivation for using Matlab to debug DSP software

In this section we describe how the normal debugging tools are not powerful enough to debug
DSP software at a functional level and we explain how Matlab can fill that role. A debugger
provides an interface to either a simulator or an emulator and can display and modify variables,
create breakpoints and control execution of the software. It shows the code that is being
executed in the language it was written. Relative to some of the tasks that a DSP must do, C is
a low-level language. The problem with debuggers is that they are operating at the same level
as the language in which the software is written, that is, a low level. It is easy, with a debugger,
to verify that the variables you are accessing are of the type you planned them to be and that
the program flow through all of the for loops and branches proceeds as you wanted it to. A
debugger is ideal for detecting the causes of run-time errors such as using pointers incorrectly or
division by zero. But a debugger does not show whether what you have planned your software
to do is flawed or incorrect. For example, suppose that you want to p write a function that
calculates the modulus, m, of a complex number, z = x + iy, where m = x2 + y2 . You might
use the following C code to do it:
m = sqrt(x*x + y*y) ;
but if x is large then x*x will cause an overflow and the function will not return a result
even though, assuming y is relatively small, the true value of m could be represented using
the machine’s precision. This is a flaw in the function that cannot be revealed by a normal
debugger which simply shows that indeed x is large and that x*x overflows. The function should
be calculated (for large x) using
xt = fabs(x) ;
yt = fabs(y) ;
tmp = yt/xt ;
m = xt * sqrt(1 + tmp*tmp) ;
As another example, suppose that you wish to write some code to find the solution to the
matrix equation, Ax = b, where A is square. The solution is x = A−1 b and so you could
implement this by calculating the inverse of A and multiplying it by b. However, the solution
by this method would be unstable and susceptible to round-off errors. Apart from showing that
the solution has no not a numbers (NaNs) and that x has the correct dimensions, a debugger
cannot show that the solution is unstable. This is the niche area of debugging that Matlab
fills. Matlab is a high-level language relative to the signal-processing tasks that a DSP may be
doing. One Matlab command may be the equivalent of dozens of C commands. By debugging
with Matlab we can detect bugs that arise through faulty program design rather than just the
unintentional mistakes that a normal debugger reveals. Matlab can be used to solve the same
equations that the DSP is solving. By communicating data from the DSP, Matlab can calculate
independent solutions that should be identical to the DSP’s solutions. Because a lot of C code
can be mimicked with just a single Matlab command, there is little chance for a mistake when
using Matlab to do the computations. Matlab’s solutions may be regarded as highly reliable
and so any discrepancy between the DSP’s solutions and Matlab’s are due to bugs in the DSP
software. In the examples given above, Matlab will show that
1. m can be calculated for large x and small y and that it is within the precision of the DSP,
and
2. the solutions using the matrix inverse are unstable (LU decomposition is a better way to
solve for x [3]).

2
3 Our DSP application – adaptive array processing
Our application is an adaptive digital-beamformer system that uses application-specific inte-
grated circuits (ASICs) and a DSP. A block diagram of the software is shown in Figure 1. The
array has eight antennas whose outputs are digitized in quadrature at 8 MHz. The ASICs
weight and sum the data to produce a single quadrature output. The adaptive algorithm, im-
plemented on the DSP, is known as a minimum-variance (MV) beamformer and it calculates
the eight complex weights that are delivered to the ASICs for the weight-and-sum operation.
The weights are calculated repetitively from blocks of data. The MV beamformer is described

measure * this operation is only done during

* memory
steering a setup or calibration stage.
vectors

quadrature
data interpolate
look direction steering
commands vectors calculate
weights to
ASICs
calc. array
covariance
matrix

Figure 1: Block diagram of the DSP software.

as follows [2, 1]. Let the digitized quadrature signal at time n from the mth antenna be given
by xm (n). The snapshot vector, x(n), represents all of the antenna signals as

x(n) = [x1 (n), x2 (n), . . . , xM (n)]T ,

where M is the number of sensors. A block of data, X, representing all snapshot vectors from
n = 1 . . . N , is given by
X = [x(1), x(2), . . . , x(N )].
An estimate of the array-covariance matrix, Rxx is calculated using

Rxx = XXH (1)

where the superscript H represents Hermitian transpose. The operator of the MV beamformer
provides a look direction relative to the array and the DSP uses this to calculate a steering
vector, a. Then the complex weights vector, w, calculated by the DSP is given by

Rxx −1 a
w= . (2)
aH Rxx −1 a
A second non-adaptive beamformer, known as a Fourier beamformer, was also implemented
in the DSP software. The operator could switch between the MV and Fourier beamformers
and this provided a control for verifying the performance of the MV beamformer. The weights
vector from the Fourier beamformer, wF , is equal to the steering vector (wF = a).
Calculating a steering vector, a, for use in (2) involves measurement and interpolation.
Under normal operation, the steering vector for an arbitrary direction is interpolated from a
small set of steering vectors that have been stored in memory. When the system is set up
specially for calibration the DSP can measure steering vectors for given directions and these
are stored for the interpolation step.
We can calculate (1) and (2) with the following Matlab code.
Rxx = XX’ ;
w = (Rxx\a) / (a’*(Rxx\a)) ;

3
The same program in C requires around 200 lines of code. The ASICs’ filtering operation can
be described as wH X. Note that if the MV beamformer fails to work properly, the fault can
lie with either the implementation of (1) or (2), the measurement of the steering vectors or the
interpolation of the steering vectors. In other words, virtually the entire program is suspect if
the beamformer does not operate correctly.

4 Debugging examples
In this section we describe our Matlab-based debugging environment and we give examples of
how we used Matlab to correct two bugs in our DSP software. Section 4.1 describes how we
discovered a problem with the part of the software that calculates the weights and Section 4.2
describes how we discovered a problem with the software that measures the steering vectors. On
the surface, these bugs may seem trivial but, as part of a complex system in which we were, at
the same time, dealing with hardware problems and which contains many interrelated software
functions, even just isolating the functions with the bugs would have been very difficult without
Matlab. Section 4.3 summarizes all of the ways in which we used Matlab in the two debugging
examples.
A serial link from the DSP to a PC was available so that an operator could send commands
to the DSP. Serial ports are a feature of DSPs so even if one is not part of an application there
is no significant extra hardware to implement serial communication with a PC. Simple messages
can be sent to and from the DSP. Each message begins with an integer tag that identifies the
content of the message and the rest of the message is any amount of binary data that we wish
to communicate. When the PC receives a message the operator’s software appends the binary
data to a file on the hard drive. Each message with, its identifying tag, is saved in a unique
file. When enough data has been written to the file or files, Matlab is run and the data is read
with scripts that are tailored to each file. Appendix A has examples of some script files that
we used to read the binary data into Matlab. Using this scheme requires a small processing
overhead on the DSP. This allows the DSP to operate with almost no additional burden and in
real time.

4.1 Incorrect weights calculation

In our first tests on the digital-beamforming system we used a single signal in a direction of 0◦
azimuth and 0◦ elevation from the array. This kept the data as simple as possible and gave us
a situation in which we knew what output data to expect so that any problems could be easily
recognized. When the system was run the Fourier beamformer appeared to work while it was
obvious that the MV beamformer didn’t. Matlab showed that the weights given by the Fourier
beamformer were as we expected. The MV beamformer’s weights should have been almost the
same as the Fourier beamformer’s while there was only one signal but they were very different.
This and the fact that one beamformer appeared to work while the other did not suggested
that there was a problem with the parts of the software that were associated exclusively with
the MV beamformer.
We saved array-covariance matrices, steering vectors and MV beamformer weights vectors
to data files and used Matlab to verify that the adaptive beamformer was indeed calculating
w = (Rxx−1 a)/(aH (Rxx −1 a)) correctly, to within the 32-bit precision of the DSP. Note that
the software used a Cholesky decomposition and not a matrix inversion to solve for Rxx −1 a.
We had expected that the array-covariance matrices would be ill-conditioned and found that
its condition number was around 105 . Given that the weights calculations were shown to be
correct we thought that the weights might be incorrect because of the poor condition number of
the array-covariance matrix. We tried improving the condition of the array-covariance matrix
by adding σ 2 I to it, where σ 2 is a positive number and I is the identity matrix. But this did not
improve the MV beamformer’s output. We saw that there were four significant eigenvalues of the
array-covariance matrix where we expected just one (for one signal). We guessed that the three
extra significant eigenvalues were due to signals generated within the hardware and plotting
the power spectrum revealed that two of the eigenvalues were associated with digital data
transmission within the hardware. We then supposed that the extra signals were corrupting the
steering-vector measurements that are necessary to run the beamformers. The MV beamformer
is more sensitive to errors than the Fourier beamformer and so we thought that explained the

4
difference in performance. Further analysis of the errors showed that they were much less than
the variance of the eigenvectors of the array-covariance matrix estimates which eliminated the
extra signals as the cause of the problem. At this point we tried moving the signal to a different
direction and that caused the Fourier beamformer to stop working also. Now it seemed that
the problem was related to a part of the software that was common to both beamformers. We
verified that the array-covariance matrix was being calculated correctly and that left only the
function that downloaded the weights to the DSP. Having narrowed the problem down to just
one function, we took a very close look at it and realized that, although the ASICs performed
the filtering correctly, the DSP was required to conjugate the weights before downloading them.
We corrected the code in one line and tested the beamformers with the signal at 0◦ azimuth
and elevation again. Both beamformers worked correctly.

4.2 Phase wrapping of the measured steering vectors

After fixing the bug in the previous section, we calibrated the array for all directions and found
that neither of the beamformers worked properly any more. The bug had to be in either of the
functions that
1. measured the steering vectors, or
2. interpolated the steering vectors.
After plotting elements of the steering vectors in Matlab it was obvious that the problem had
to be in the measurement function. Figure 2 shows plots of the amplitude and phase of one
of the internal components. The phase plot shows the effects of phase wrapping. The jumps
in the plot are not 2π because the measurement function takes a linear combination of the
measured phases and the linear weights are generally not unity. We checked that the function
that calculated the linear combination was working correctly and that narrowed the bug down
to a small section of code. The bug was finally found to be due to an incorrect application of
the standard C-library fmod() function. We were using it in such a way that the conversion
of an arbitrary number to a value in the range (−π, π) was correct for only 50% of numbers.
The amplitude plot of Figure 2 was not as smooth as we had hoped and so too we were unsure
of how accurate its interpolation would be. We measured the variances of the steering-vector
amplitudes. They showed that our measurements were reliable but we could see from the plot
that our original plan to use 5th -order interpolation might give results that oscillated too much.
We changed the interpolation to 2nd order and the adaptive array system worked completely.

28
200
26

24 0
Phase (degrees)
Amplitude

22
−200
20

18
−400
16

14 −600
−50 0 50 −50 0 50
elevation (degrees) elevation (degrees)

(a) (b)

Figure 2: Amplitude (a) and phase (b) of the steering vectors versus elevation.

5
4.3 Summary of the ways we used Matlab
The following list gives all of the ways that we used Matlab as we described in the last two
sections:
1. checked that the calculation of (2) was correct,
2. estimated the condition number of the array-covariance matrix,
3. estimated the eigenvalues of the array-covariance matrix,
4. computed and displayed the power spectrum of the quadrature data,
5. estimated the variance of the eigenvectors of the array-covariance matrix,
6. checked that the calculation of (1) was correct,
7. plotted the measured steering vectors versus direction, and
8. estimated the variances of steering-vector measurements.

5 Conclusion
Normal DSP debugging tools are insufficient to debug some functions of DSP software because
they are too low level in relation to the DSP functions. We have used Matlab as part of
our DSP debugging cycle by exporting data from the DSP to Matlab. We are then able to
verify the operation of the DSP functions and analyze the data further, if necessary. We
gave examples of how we applied Matlab-based debugging to our adaptive digital-beamforming
system. Exporting the data to Matlab was a simple task that did not noticeably burden the
DSP which allowed it to run in real time. Matlab’s powerful functions allowed us to test DSP
results and data, often with a single command. We were able to spot and fix a potential bug,
choosing the order of interpolation to be too high, by viewing data in plots. Using Matlab as
a debugging tool sped our debug cycle by an estimated six times over a normal debugger.

References
[1] Simon Haykin. Array signal processing. Number ISBN 0-13-046482-1 in Signal processing
series. Prentice-Hall, 1985.
[2] S. Unnikrishna Pillai. Array signal processing. Springer-Verlag, 1989.
[3] William H. Press, Saul A. Teukolsky, William T. Vetterling, and Brian P. Flannery. Nu-
merical recipes in C. Cambridge University Press, 2nd edition, 1992.

A Matlab script files

In all of the binary-data files complex data is stored real followed by imaginary. Floating-point
values are in 32-bit float format.

A.1 Reading array-covariance matrix files

Array covariance matrices are stored to file in row order. They are 8 × 8 and any number of
them are stored in the one file. This script creates one matrix ai, where i is an integer ≥ 1, for
each array-covariance matrix and it puts the number of matrices that it read in an.
% Load in the array-covariance matrices that are stored in file
% dsp_cal.acm. End of file is reached when a fread returns an empty
% matrix. Open the file and allocate matrices.
an=0; tmp=0;
fd=fopen(’dsp_cal.acm’);
ac=zeros(8);

6
% Read the data.
while (~isempty(tmp))
an=an+1;
for c=1:8
for e=1:8
tmp=fread(fd,1,’float’);
if isempty(tmp) break;
else ac(c,e)=tmp; end
ac(c,e)=ac(c,e)+i*fread(fd,1,’float’);
end
end

% Assign the matrix to ai

eval([’a’,num2str(an),’=ac;’]);
end
an=an-1;

% Close the file.

fclose(fd);

A.2 Reading steering vector files

Steering vectors are written to file following two floats that are the azimuth and elevation
directions given by the operator. The azimuth directions are returned in ld(1,:), the elevation
directions are returned in ld(2,:), and the steering vectors are returned in sv which has 8 rows
and a number of columns equal to the number of steering vectors in the data file. The script to
read weights vectors is identical to the steering vector script except that it opens the file called
“dsp cal.wvc”.

% Load in the steering vectors that are saved in the file dsp_cal.svc.
% End of file is reached when a fread returns an empty matrix.
ns=1000;

% Open the file and allocate matrices

fd=fopen(’dsp_cal.svc’);
sv=zeros(8,ns);
ld=zeros(2,ns);

% Read the data

for c=1:ns
% azimuth and elevation directions
tmp=fread(fd,1,’float’);
if isempty(tmp) break; end
ld(1,c)=tmp;
ld(2,c)=fread(fd,1,’float’);
% steering vector
for d=1:8
sv(d,c)=fread(fd,[1 1],’float’);
sv(d,c)=sv(d,c) + i*fread(fd,[1 1],’float’);
end
end

% Close the file and remove the empty parts of the matrices.
fclose(fd);
sv=sv(:,1:c-1);
ld=ld(:,1:c-1);