GNAT & Quantify

[Frode Tenneboe <ft@alne.edh.ericsson.se>]

I thought I should share with you how to I got Quantify to work with
GNAT. Even though the process itself is quite straight forward the
path to get it all together was rather longish.

For most of my test I have used SUN Solaris 8 for Sparc and GNAT 3.13p.
Other configurations might also work.

It began sometime in 2001 with mail back and forth to Rational, it
continued in 2002 and I got a few protos (I weared out a few support
engineers in the process :). I believe the first proto which gave 
useful results was 2002a.06.00-proto0031 (PrifyPlusFamily).

Many protos after, I'm now currently at 2003.06.00.

There are a few things to be aware off before starting using Quantify.
However, when everything is sorted out (which I hope this instruction
will tell all you need to know) the result is worth it.

Firstly, you need to set which part of the code you want to quantify.
Put the following in a suitable place in your code:

   procedure C_Quantify_Clear_Data;
   pragma Import (C, C_Quantify_Clear_Data, "quantify_clear_data");
   procedure C_Quantify_Save_Data;
   pragma Import (C, C_Quantify_Save_Data, "quantify_save_data");

Then call C_Quantify_Clear_Data and C_Quantify_Save_Data just
before and after the code you want to profile. You may instead want
to call to exit() which will save data for the entire run of
the program (or since last Quantify_Clear_Data()). It is also
possible to install signal handlers to control this (see later).

Then you need to instrument Quantify into your executable. I have
deviced a small script which does that. Put it in a safe place
and call gnatmake as instructed:

#!/bin/sh -v
#Usage:
#gnatmake [...] -largs --LINK=cgcc 
#(or: cgcc b~xxxx.o xxxx.o libgnat.a)

quantify \
         -optimize-basic-block-insertion=no \
         -verify-basic-block-updates=yes \
         -force-rebuild \
         gcc $*

(the two first parameters I found I neede for tasking programs,
-force-rebuild is handy if you change some parameters.)

[...] just means that you use your call gnatmake as usually with 
the extra parameters just appended. If you want the most detailed level
of granularity you need to compile and link with the -g debugging option.

Before you run your program you need to set up a suitable
environment:

setenv QUANTIFYOPTIONS "-api-handler-signals=SIGUSR1,SIGUSR2 -max_threads=400 -record-child-process-data"

The first option enables signal handles in Quantify which means that you may
use (in this case) SIGUSR1 and SIGUSR2 (ie. kill -SIGUSR1) to save and
clear data respectively. I have not found this method to be entirely
reliable so I prefer one of the methods described above. The second
tells quantify to allow this many threads and no more and the third
allows it to continue profiling in fork/vfork.

You are now ready to run your program. Unfortunately, the two first
parameters used to call quantify to instrument the code (see above)
also generates A LOT of garbage output to stderr. So to get any
decent result from a program running more than a few seconds you HAVE
to start the program with:

#> program 2> /dev/null

(ie. redirecting stderr to /dev/null. Different shell, different syntax).

If all is well now it should run as normal and pop up a new Quantify
window. If you have used the signal handles or the clear/save calls,
(a) file(s) will have been saved where you started your application.
The filenames will be on the format [program].[pid].[no].composite.qv.
Run qv [file] to view the result.

At this point there are a few more things to be aware of. If a
procedure/function contains exception-handling it will only
provide data of function-level granularity. Tasking also seems
to be a problem if rendez-vous are involved. I have not managed
to isolate this problem. I just removed the rendez-vous (since it
was the client code I wanted to profile). Similarly, I removed the 
exception handling code where appropriate to get the required detail. 

Even though Rational offically does not support GNAT, they were
quite helpful and supportive most of the way. However, they have
now officially decided that they were not able to continue
my support case. Now that GNAT is part of the GCC tree it might
be possible to get more support in the future.

I hope this was helpful. 

Regards,
 -Frode

-- 
^ Frode Tenneb�               | email: Frode.Tennebo@ericsson.com ^
| Ericsson AS., N-1788 Halden | Phone: +47 67 25 09 39            |
| with Standard.Disclaimer; use Standard.Disclaimer;              |