OpenDX with ClassicGuard Help Contents
Description
We have developed a mechanism that allows OpenDX
(DX) to graphically visualise the comparison output of ClassicGuard
(Guard). This capability is important since it aids us in understanding
complex or large data structures. More information on obtaining
OpenDX can be found at the end of this page.
Prerequisites
It is assumed that ClassicGuard (Guard), OpenDX (DX), and the
necessary visualisation modules have been installed correctly.
Functionality
The current DX support for Guard is able to visualise 1, 2, and
3 dimensional arrays.
Extensions
There are two ways to extend the current functionality:
- Additional C code is written that translates AIF output to
DX input. This additional code is necessary to make DX understands
other types of data structure (e.g. lists)
- Additional DX module is written to enable the user visualises
the current supported data structures using different visualisation
methods (e.g. glyphs)
Walkthrough
The following walkthrough gives a description on
how to use ClassicGuard with OpenDX support. As an example of
a debugging session, two C codes are provided:
#include<stdio.h>
int main()
{
int a = 10;
int b = 20;
int c[2];
int d[2][2];
int e[2][2][2];
c[0] = 1;
c[1] = 2;
d[0][0] = 1;
d[0][1] = 1;
d[1][0] = 2;
d[1][1] = 2;
e[0][0][0] = 1;
e[0][0][1] = 2;
e[0][1][0] = 3;
e[0][1][1] = 4;
e[1][0][0] = 5;
e[1][0][1] = 6;
e[1][1][0] = 7;
e[1][1][1] = 8;
printf("%d\n", a);
printf("%d\n", b);
printf("Hello\n");
printf("World\n");
return 0;
} |
#include<stdio.h>
int main()
{
int a = 10;
int b = 20;
int c[2];
int d[2][2];
int e[2][2][2];
c[0] = 5;
c[1] = 3;
d[0][0] = 1;
d[0][1] = 2;
d[1][0] = 3;
d[1][1] = 5;
e[0][0][0] = 5;
e[0][0][1] = 2;
e[0][1][0] = 4;
e[0][1][1] = 4;
e[1][0][0] = 7;
e[1][0][1] = 6;
e[1][1][0] = 7;
e[1][1][1] = 9;
printf("%d\n", a);
printf("%d\n", b);
printf("Hello\n");
printf("World\n");
return 0;
}
|
Copy the code in the left column into a file and
save it as test1.c, save the code in the right column
as test2.c. Compile both codes with debugging symbols
and save them as test1 and test2 respectively.
Visualising 1 dimensional array
As the first example, we visualize the difference
between variables c in test1 and test2. Start
a Guard session as exemplified below:
1 $ guard
2 GUARD Parallel Relative Debugger
3 Copyright (c) 1996-2002 by Guardsoft Pty Ltd
4
5 dbg all> invoke $a test1
6 Found debugger version (Sat Aug 9 14:50:32 GMT 2003)
7 Debugger architecture is powerpc-apple-darwin6.6
8
9 Initial breakpoint, main () at test1.c:5
10 dbg all> invoke $b test2
11 Found debugger version (Sat Aug 9 14:50:32 GMT 2003)
12 Debugger architecture is powerpc-apple-darwin6.6
13
14 Initial breakpoint, main () at test2.c:5
15 dbg all> graph $g
16 > set display "vis_opendx"
17 > assert $a::c@"test1.c":13 = $b::c@"test2.c":13
18 > end
19 55 nodes successfully processed
20 Graph g compiled.
21 dbg all>
The important lines are line 16 and line 17. In line 16, we set the display argument to "vis_opendx" to tell Guard to invoke DX to show the differences. In line 17, we put an assertion on variable c. After this, we can start visualising the difference by typing start $g in the Guard
command line. If everything runs correctly, you will get something similar to the
following screenshot (on Mac OS X):
The DX window looks something like:
For 1 dimensional array, the current DX module displays the differences
as circles. The size and the colour of the circle indicate the
size of the difference. A large circle indicates a large difference
between two array elements. The largest difference is indicated
by the red colour, the smallest difference is coloured by the
blue colour, while the other differences are showed with the colour
between red and blue. In this example, the red circle represents
4 (5-1) and the blue circle represents 1 (3-2). The x-axis shows
the array index (i.e. 0 and 1). The y-axis shows the size of the
circle.
If the image is not displayed properly, we can click Options->Reset
in the DX window to reset the image to the default view. The image
can be rotated or zoomed by clicking Options->View Control
and selecting the desired mode:
After selecting the desired mode, for example Rotate,
go back to the DX window and drag the image to rotate it. Click
Options->Reset to reset the image.
Visualising 2 dimensional array
For an example of visualising 2 dimensional array difference, just follow the same procedures as exemplified in the above Guard session but we use a different assert statement:
assert $a::d@"test1.c":18 = $b::d@"test2.c":18
If everything runs correctly, the following window will be displayed:
As an example of DX capability, we choose to display the difference
between two 2 dimensional arrays as a rubber sheet surface. The
x-axis and the y-axis show the array indices. The colour indicates
the size of the difference. Red colour indicates the largest difference,
blue colour indicates the smallest difference, while the colour
between red and blue (i.e. green in this example) indicates the
other differences. The z-axis also indicates the size of the difference:
Visualising 3 dimensional array
An example of 3 dimensional array difference can be obtained
by using the same procedure like above with this assert statement:
assert $a::e@"test1.c":27 = $b::e@"test2.c":27
The difference between two 3 dimensional arrays is displayed as a 3 dimensional
space with glyphs showing the differences:
The axes (x, y, and z) show the array indices. The colour and
the size of the glyphs indicate the size of the difference. For
example, the largest difference which is 4 (e[0][0][0]
of test2 which is 5 minus e[0][0][0] of test1
which is 1) is indicated by the red glyph at position (0,0,0).
Limitations and Bugs
Only 1, 2, and 3 dimensional arrays that are supported.
Obtaining OpenDX
OpenDX (source code and binary distributions) can
be obtained from the OpenDX
Download Site. More information can also be found in the Installation
and Configuration Guide.
