TRPROF.TXT                                                              ThR
                                                                 2001-04-01


TRPROF Thomas' Atari ST profiling tool.

You are writing programs for the Atari ST/TT/Falcon and want to optimize
speed?

TRPROF is a tool to help you with this.
It shows you where processor time is spent across your program. Thus you
can identify "hot spots" that dominate performance of your code. Then you
can go optimize these specific parts of the code.

Prerequisites:
-	TOS compatible multitasking operating system

-        You need another program to tell where your program under
        investigation is located in memory (e.g. MEMEXAMN.TTP under Magic
        or SYSMON)

-        No other program running concurrently must use timer A of the MFP
        (see below)


Installation

Just copy TRPROF.PRG and TRPROF.RSC to any location you like and start
TRPROF.PRG from there.


Procedure

You do not need to compile your program with any special options. 
However when linking make sure you get a listing of the symbols used in 
your code. Thus you get information where functions/procedures 
start relative to the start of your program. Alternatively you may 
direct the linker to include a symbol table in the executable PRG 
or APP file. Then you use the NM tool from the developer tool-kit 
or from Julian Reschke's PROGTOOLs to get the symbols' values or you 
use a debugger to find out symbol values. Alternatively you may 
use a tool like TTDIGGER to find out what starts where.
Further you need to find out the length of the TEXT segment of the program
under investigation. The SIZE tool from Julian Reschke applied to the
PRG/APP file gives you this information.

Then you start the program under investigation as usual.
Next you find out where in *memory* that program was loaded. 
There are several tools that can do this. For Example SYSMON can locate
programs in memory. Or: with Magic comes the tool MEMEXAMN.TTP to list all
allocated memory blocks. Among these are also the memory blocks occupied by
loaded programs. A program can be identified by the text "Basepage" in the
rightmost column of the MEMEXAMN output. The Start Address shown by Magic
is however the address of a Memory Descriptor block of 16 bytes lenght
which precedes the basepage. Under TOS the basepage is 256 bytes long and
always precedes the TEXT segment. MEMEXAMN.TTP also shows the length of the
program loaded. This is however the length of the memory block allocated to
the program in total i.e. MemoryDescriptor+TEXT+DATA+BSS.

When you got the information where the code starts and how long the TEXT
segment is then you start TRPROF.PRG. It has a simple GEM user interface in
an AES window. You type:

__________  Start address
The basepage address

__________  Offset
The length of the base page (256)

__________  Code start address
The start address of the TEXT segment
This field is automatically calculated as Start address + Offset. To have
these two input fields is just a convenience to avoid the need for a
calculator.

__________  Code length
The lenght of the TEXT segment

__________  Code end address
This is the address of the byte after the TEXT segment.
This field is automatically caculated as Code start address + Code lenght.

Note that you specify decimal input as usual and hexadecimal input in C
language notation by starting with 0x....

By toggling the check mark left to "Hex output format" you can switch the
format of the calculated fields to decimal or hex.

When you are happy with input fields to TRPROF you hit the Start button.
This starts TRPROF's internal profiling activities. Do not worry as nothing
seems happen or show up except the Stop button will become selectable. You
may notice some small slowdown on systems with an 8MHz 68000 only but that
is normal.

Next you start using the program under investigation and do the tactivities
you want to optimize or benchmark.

When you are finished you revert back to TRPROF and hit the Stop button.
Then TRPROF writes the profiling result as the file SCRAP.TXT to the
system's GEM clipboard from where you can paste it using e.g. any text
editor. Alternativly you may just copy the file SCRAP.TXT.


Interpretation of TRPROF output

The output from TRPROF are three pieces:
The header repeates the address information you put into TRPROF's entry
panel.

Next comes a summary section:

PC < Text start
        How many times the processor's program counter (PC) was found to be
        in memory *below* your code and as a percentage of the total.

Text start <= PC <Text End
        How many times the PC was found just to point into your code i.e.
        some your code was executed plus the percentage of the total.

Text End <= PC
        How many times the PC was found above your code plus the percentage
        of the total

Next comes a histogram showing in detail where the PC was found to point
into you program.

The first column shows the bin start as a hexadecimal address offset from
the start of the text segment and the second column is the count how many
times the PC was found to be equal or greater than the bin-start and lower
than the start-address of the next bin. Thus you see where processor time
is spent most of the time. Try to identify peakes in the histogram with
functions in your code by reconciling it with the symbol table or a listing
or a debugger as written above.

You might want to redo the profiling execise with different start and end
addresses (code length) in TRPROF to "zoom" into your code thus getting a
finer grained histogram that allows you to examine the "hot spots" down to
the processor instruction level.


How TRPROF works

When you hit "Start" TRPROF sets up a clock using the MFP's timer A device
that fires an interrupt about every 100 microseconds. The interrupt routine
looks where the program counter has been when the processor was interrupted
and increments the corresponding histogram bin by one.

When you hit "Stop" TRPROF deinstalls the Timer A interrupt and writes
header, summary information and the histogram to the GEM clipboard.

You may use Start and Stop from TRPROF as often as you like without the
need to finish and restart TRPROF.PRG. However please note that every time
the clipboard gets overwritten. So make sure you paste the result somewhere
to save it.


Usually you will find that the PC is quite often executing code above or
below your code. Below will be AUTO folder programs and/or device drivers,
accessories or eventually the operating system loaded from disk. Above may
be programs you loaded after your program or code from a ROM-TOS.


Bugs

The Hex/Decimal switch only applies to the GUI. The clipboard-file's
addresses are still always hex.

The impact of higher priority interrupts than MFP-Timer A on the profiling
results is not yet clear.


Disclaimer

This package is provided to you as is. I do not guarantee any features nor
do I take any responsibility for any damage or loss you may suffer when
using this software.


Contact Information

Suggestions, bug reports, flames to

Dr. Thomas Redelberger
EMail:     redetho@gmx.de
FAX:       +49 6023 999410

Copyright 2001 Dr. Thomas Redelberger

