@DATABASE "AProf.guide" @remark Profiler Dokumentation für Version 3.3 @remark @remark $RCSfile: AProf.guide $ @remark @remark $Revision: 1.7 $ $Date: 1994/10/04 11:28:35 $ @remark ****************** @remark * Main @remark ****************** @NODE Main "AProf.guide" Documentation for Amiga Profiler V3.30 © 1993,94 Michael G. Binz @{" What is a profiler? " link l-what} @{" System requirements " link l-sysrequ } @{" Installation procedure " link l-install } @{" Starting the profiler " link l-start } @{" User interface " link l-ui } @{" Configurability " link l-config } @{" Notes " link l-notes } @{" Tested Systems " link l-systeme } @{" Caveats " link l-caveats } @{" StripB " link l-stripb } @{" Feedback " link l-feedback } @{" AProf needs you..." link l-enforcer-blah } @{" Copyright " link l-copyright} @{" Changes " link l-changes } @{" Q+A " link frageantwort } @ENDNODE @remark ****************** @remark * Was isses??? @remark ****************** @NODE l-what "AProf:What is a profiler" A profiler is a development tool supporting the developer in code optimization. A specified program is executed by the profiler which collects several informations (ie. call counts, time values) while execution. This data can be used to locate the so-called hot spots in your code - functions where most of the execution time is spent and optimization will gain most effect. The following articles supply further information on profilers: o Dr. Dobb's Journal, January 1993 Joseph Newcomer, 'Profiling for Performance', pp. 80 o Dr. Dobb's Journal, November 1993 Michael R. Dunlavey, 'Performance Tuning: Slugging it out', pp. 18 @ENDNODE @remark ****************** @remark * Installation & Systemanforderungen @remark ****************** @NODE l-sysrequ "AProf: System requirements" o Hardware requirements The profiler needs at least Workbench/Kickstart 2.04 and a minimum of 500K available memory (depends on profilees sizes). It has been tested successfully with Amiga 500, 2000, 3000, 4000 and OS versions 2.04, 2.1, 3.0. o Software requirements Your compiler must be able to create Amiga symbol hunks. Code symbols included in this hunks should only address the starting addresses of functions in your code. No intermediate jump labels must be defined. (See @{ "Clean symbol tables" link frageantwort}, @{ "Tested compilers" link l-systeme }) @ENDNODE @NODE l-install "AProf:Installation procedure" Copy all files included in AProf3_30.lha into a directory and add this directory to your PATH. Do not delete AProf's icon (AProf.info), since configuration data is located in this file (See @{"Configurability" link l-config}). @ENDNODE @remark ****************** @remark * Start & Oberfläche @remark ****************** @NODE l-start "AProf: Starting the profiler" From CLI the profiler is started with 1.> AProf [application] The profiler starts up, displays its user interface, loads the symbol tables from the file 'application' if specified and waits for your actions. From Workbench, doubleclick the AProf icon. If no filename was specified or if started from workbench, you can load a file from the menu @{ "[Files/Open]" link m-files }. See also: @{ "User interface" link l-ui } @ENDNODE @NODE l-ui "AProf:User interface" Title: Name of loaded profilee Menus: @{ " Files " link m-files } @{ " Action " link m-action } @{ " Data " link m-data } @{ " Move " link m-move } @{ " Misc " link m-misc } Displays: @{ " Mode " link gad-inex } @{ " Time unit " link gad-percmil } @{ " Sort " link gad-sort } @{ " Time " link gad-xtime } Buttons: [ Shortcuts for often needed menu entrys ] Description of table entrys: Function HitCnt Per Call Over Min/Max | | | | | Symbol names* | | | | | | | | Call count** | | | | | | Average execution time per call | | | | Overall execution time for that function | | Minimum/maximum execution time per call * The symbol *ENTRY*, if displayed, is generated by AProf if the symbol table of the profilee contains no symbol sitting at the very first executed address of its seglist. ** A call count value of -1 is shown for symbols being no function entrys. Safe profiling must be active. [ Status and error messages are displayed in the bottom window border ] @ENDNODE @NODE m-files "AProf:Menu: Files" Menu: Files Reading and writing profiler data. Open: Read a new file (also accessable via button) Save: Save report to file with same basename and suffix .pro Save as: Save report to selectable file Reset: Reset all timing values Print: Print report Exit: Leave the program @ENDNODE @NODE m-action "AProf:Menu: Action" Menu: Action Start the profiling process. Start: Starts the profile run. If you restart a profilee, then times are added. If you want to run a profilee several times without adding the times and hit counts, you must reset the timer and hitcounts with @{ " Files/Reset " link m-files }. (also accessable via button row) @ENDNODE @NODE m-data "AProf:Menu: Data" Menu: Data Runtime configuration and execution control. Exec details: Provide a command line and stack size for the profilee See: @{ "Exec dialog" link dialog-exec } Preferences: Configure the profiler. See: @{ "Preferences dialog" link dialog-preferences }, @{ "Configurability" link l-config }. @ENDNODE @NODE m-move "AProf:Menu: Move" Menu: Move Moving in the display area. Find: Enter a search string and start search Find next: Search for next occurence Top: Go to top of symbol table Bottom: Go to bottom of symbol table Page up/down: One page up/down @ENDNODE @NODE m-misc "AProf:Menu: Misc" Menu: Misc Other functions Help: Start the AmigaGuide(TM) hypertext help system (if available) Refresh Window: Redisplay symbol table About: Display version and copyright information @ENDNODE @NODE gad-inex "AProf: Profiler mode: Separate/Combined" Separate/Combined: (Mode) Displays how function timing values are accumulated. If combined is selected, the time value for a function includes the times of all functions that are called by this function. Separate excludes the times of called functions. Note that if your code includes recursive procedure you must use separate mode. If combined is used, the time for the recursive procedure is wrong. Example: int main( void ) { foo( 2 ); /* foo needs 2secs execution time */ bar( 3 ); /* bar needs 3secs execution time */ ...burn 1sec proc. time in main()... return 0; } If 'Separate' is selected, the profile list will look like this: Symbol HitCnt Per Call main 1 1000 The timing values are updated for foo 1 2000 each funktion separate. bar 1 3000 Now if 'Combined' is selected: Symbol HitCnt Per Call main 1 6000 The timing values for foo() and foo 1 2000 bar() are added to main(), since bar 1 3000 main() calls both. @ENDNODE @NODE gad-percmil "AProf: Cycle: Percentual/Millisecond timevalues" Millisecond/Percentual time units: (Units) Displays the units used for for timing values. If percentual is active, times shown are fractions of overall execution time in percent. @ENDNODE @NODE gad-xtime "AProf: XTime" Overall execution time of profilee. Units are seconds or milli- seconds depending on execution time. Times longer than 1000 ms are displayed in seconds (s), below in milliseconds (ms). @ENDNODE @NODE l-config "AProf: Configurability" All configurable items of AProf must be set as ToolTypes in AProf's .info file, which must reside in the same directory as the profiler. +------------------------------------------------------------------+ | Never delete AProf.info! All configuration data will be | | written to this file! | +------------------------------------------------------------------+ Beginning with version 3.30 one can save AProf's current settings with the 'Save' button in 'Preferences'. It is recommended to use this instead of setting the ToolTypes manually. o WINDIM=left/top/width/height Use this to set size and position for the profiler window. o TUNITS=(PERCENTUAL | MILLISECOND) Default time units. o PMODE=(COMBINED|SEPARATE) Profiling mode o PATTERN=(AmigaPattern) Amiga pattern for symbols to hide. Look in your Amiga User Manual for a description of pattern syntax o SORT=(NONE | NAME | HIT | AVERAGE | OVER) Specify the sort order you prefer. o SAFE=(TRUE | FALSE) Safe profiling on or off @ENDNODE @REMARK **************** @REMARK * Allgemein Blah... @REMARK **************** @NODE l-notes "AProf: Notes" Implementation -------------- AProf is an active profiler. This means, hit counts and timing values are measured by employing a sophisticated breakpoint scheme. Before a profilee is executed by AProf, all function entry points are marked with breakpoints. After execution is started, AProf receives the breakpoint hits and places additional breakpoints at the function return points. The address for function return points is derived from the stack. This should make it clear why AProf needs a 'clean' symbol table: There is no foolproof way to figure out the function return address if there are any function local data on top of stack. Actually some testing can be undergone to ensure the correct values are read from the stack. This can be activated in AProf versions > 3.22 by the checkmark 'safe profiling' in AProf preferences. Although this is not foolproof as stated, it works unexpected good with most compilers. The disadvatage of this technique is the additional time spent in the checking routines. Profilee environment -------------------- Wether AProf is started from CLI or workbench, the profilee's environment is always a shell. If started from wb, a shell window will be supplied for profilee IO. ARexx port ---------- In the current version AProf provides no additional functions for ARexx hosts. @ENDNODE @NODE l-caveats "AProf: Caveats" Here is a list of known constructs which can result in problems if you try to profile programs including them o Non-standard startup code ------------------------- The profilees must be able to run in the same process environment as the profiler. It's not possible to use special startup codes for detaching a program or making it resident. o recursive procedures -------------------- Use only '@{ "separate" link gad-inex }' profiling mode if your code includes recursive procedures. In combined mode the time for the recursive procedure is wrong. o setjmp()/longjmp() ------------------ If setjmp()/longjmp() combinations are used in the profilee, the time span between calling longjmp() and the next RTS instruction will add to the function calling longjmp(). o signal()/raise() ---------------- Most compiler libraries contain signal()/raise() functions which are not compatible with AProf. o CIA Timer --------- CIA timers are not available for profilees. o Overlays -------- Profiling of overlayed programs is not possible. o Runtime limitation ------------------ Profiler timers can measure maximum time spans of about 99 mins. o Static functions ---------------- Functions to be measured must be in the symbol table. This is not the case for static (module local) functions in most programming environments. o Traphandlers ------------ If your program uses a private trap handler, traps not handled must be propagated to the previous handler. Used traps must be allocated with AllocTrap(). Profiling is NOT possible if you are using trace traps (#9). o Switch- and Launchfunctions --------------------------- Profilees using members tc_Switch and tc_Launch in Exec's Task structure must propagate execution to previous defined handlers. @ENDNODE @NODE l-stripb "AProf: StripB" StripB is a command line utility which can be used to remove all HUNK_SYMBOL- and HUNK_DEBUG-hunks from an Amiga executable. Command line: StripB infile outfile @ENDNODE @NODE l-systeme "AProf: Tested systems" This is a list of systems I have tested the profiler with. If you find an error or if you have tested a system not included here, send a message please. @{ " Amiga E " link amiga-e } @{ " Aztec C " link manx-c } @{ " DICE C " link dice-c } @{ " GNU C/C++ " link gnu-cpp} @{ " SAS C 6.3 " link sas-c } @{ " Maxon C++ V1.2.1 " link maxon-cpp } @{ " Assemblers " link assemblers } @{ " Other systems... " link other } @ENDNODE @NODE amiga-e "AProf: Tested systems: Amiga E" AProf works with all versions of Amiga E >2.1b. Problems: Profiling of programs using exeptions leads to meaningless results Creation of symbol hunks: Use -s switch @ENDNODE @NODE manx-c "AProf: Tested systems: Aztec C" Manx Aztec C V3.4 - V5.2b Creation of symbol hunks: Use option -w for the linker Problems: o Remove symbols named '_H#[0-9]_org' o Don't use detach.o with programs you want to profile. o ANSI C functions signal() and raise() don't handle traps the way they should. (see @{"Caveats" link l-caveats}, custom trap-handlers) @ENDNODE @NODE sas-c "AProf: Tested systems: SAS C" SAS C ? @ENDNODE @NODE maxon-cpp "AProf: Tested systems: Maxon C++" Maxon C++ V1.2.1 Problems: Code and data symbols in link libraries reside in the same hunk. According to Jens Gelhar this will change in future versions of the library. The beta version of the updated compiler writes symbol hunks as needed by Aprof so the library problem requires a simple recompile. Compiler is adding labels named L'num' to symbol table. This must be removed (Pattern: L#[0-9]) or you must activate 'save profiling'. Creation of symbol hunks: For command line compiler use option -bs. In the integrated environment use menu 'Compiler options'. Other: Test the procedure rexx/maxoncpp.aprof for unmangling of c++ symbol names. @ENDNODE @NODE dice-c "AProf: Tested systems: DICE C" DICE C V2.06.21 unregistered version Problems: Dice generates dirty symbol tables, activate 'Safe profiling'. Creation of symbol hunks: Use option -s for DCC. Information about the commercial DICE system welcome. @ENDNODE @NODE gnu-cpp "AProf: Tested systems: GNU C/C++" GNU gcc - 2.3.3 Problems: Profiling programs using ixemul.library is not possible, use static linking. Activate 'Safe profiling'. Creation of symbol hunks: Always created, to not create them use -s or @{ " StripB " link l-stripb }, which is included in this AProf distribution. @ENDNODE @NODE assemblers "AProf: Tested systems: Assemblers" AProf is tested with a number of assemblers (Aztec as, asm68, DevPack). There seem to be no problems as long as the following rules are obeyed: o If you export code symbols other than function labels, activate 'Safe profiling' in [Data/Prefs]. o Don't be too creative with your control flow, eg. several starting points for functions etc. Although this will not crash AProf, the results provided will be a bit random :) o Do not mix data and code in one hunk. o Do not use self modifying code. @ENDNODE @NODE other "AProf: Tested systems: Other..." Here is a little strategy to test if your system is able to cooperate with AProf. Step 0. ------- First, try to find out if your system can generate executables with Amiga symbol hunks. You should find this information in your compiler documentation. Then after successfully creating a executable version of the program to test, first check if your program is at least stable enough to run stand-alone without crashing the machine. Close all applications so that if a crash happens no data is lost! Step 1. ------- Start AProf and load your program. Then specify in [Data/Prefs] the symbol pattern '#?' (without quotation marks). This removes the complete symbol table, which results in a reduced protocol between AProf and your program. When this is done, close your eyes and start your program (if you have problems in finding the right keys you can keep your eyes open). If your machine crashed, then Aprof is definitely incompatible with this programming system. The only thing to do is to reboot your machine an delete AProf. If there was no problems and your program is running, take all steps needed to stop your program. Step 2. ------- Next step is to remove all symbols but one, which should be generated by you. If your programm contains a function 'foo' written by you then open the prefs request and insert ~(foo) as symbol pattern. After selecting 'use', this should be the only symbol displayed (it is possible, that there is an second symbol called *ENTRY* - this is used by AProf, ignore it). Start execution. If everything works, then again stop your program or wait for termination. Now Aprof should display the function timings. A crash is a sign for incompatibility. Forget AProf. Step 3. ------- Now remove the pattern in [Data/Prefs] and activate 'Save profiling'. Then take a look at the symbol list. Remove temporary labels or line number labels. Examples: _L0001, _L0002, _L0003, _L0004, ... _H0_org, _H0_end, _H1_org, _H1_end, ... @0001, @0002, @0003, ... Then again start execution of your program. If everything works as it should you did it. Exit your program and AProf will generate the timing report. AProf seems to be compatible with your programming system. Save the pattern created in the preceding step and use it in future profiling sessions. If your program crashed, the hard work begins. As we saw in Step 2, your programming system basically should work with AProf. So there must be one or several data objects in your code hunks. You will have to find and remove them. Step 4. ------- Save all settings. @ENDNODE @NODE l-feedback "AProf: Feedback" Contact me under EMail: michab@informatik.fh-augsburg.de If it's not possible to use EMail, write to: Michael Binz Bahnhofstr. 11 D-86459 Gessertshausen If you made tests with a compiler not listed in 'systems', please send me a small demo source file, the translated executable (with symbol hunk) and some information about creating symbol hunks with your compiler. If needed, send a description of problems and actions you performed to solve them, too. @ENDNODE @NODE l-enforcer-blah "AProf needs you..." ... if you have access to an Amiga with MMU! Since I'm developing AProf on an Amiga 2000 with 68000 I can't check for ENFORCER HITS! Although much care was taken to keep this nasty sort of bugs out of my code, there must be some. Anywhere. So man, read the following! if ( found_enforcer_hit() ) { if ( have_access_to_email() ) Send_Micha_An_Email_Report( ); /* Really! */ else if ( !too_lazy() ) Send_Micha_SnailMail_Report(); /* Cool... */ else GuruForever(); /* Gnah... */ } @{ " Micha's address? " link l-feedback } @ENDNODE @NODE l-copyright "AProf: Copyright" This software is freeware. You are allowed to copy, distribute and use it, as long as you don't change the software and distribute only the packed file (AProf3_30.lha). You are not allowed to charge a fee higher than Fred Fish's for copy- ing and distributing. These files and their related documentation, utilities and examples are provided "AS-IS" and subject to change without notice; no warran- ties are made. All use is at your own risk. No liability or respon- sibility is assumed. This software, the included utilities and documentation are © 1993-94 Michael G. Binz @ENDNODE @remark ************* @remark * Abgesang @remark ************* @NODE l-changes "AProf: Changes" V 3.34 Bugs fixed: o Screen updates caused enforcer hits o Shell display of command line caused enforcer hit Changes: o Console window opened when started from WB now has close gadget o XTime display uses [s] if [ms] value exceeds 1000 V 3.30 Future: o Passive (interrupt controlled) profiling mode Known Problems: o AmigaGuide needs 'topaz' or maybe another fixed width font to be the system default font. If another font is used, AmigaGuide fails silently. Changes: o If run from WB the profiler acts as shell for profilees o System default font is used o Added sorting functions o Extended configurability o Maximum command line length is now 256 chars o Special 'safe' profiling mode added o ARexx Port for custom symbol name unmangling Bugs fixed: o Use of other fonts than topaz.8 trashed window o Catched some enforcer hits o Initial window size was wrong o Syntax error in a pattern led to an endless loop V 3.20 o First released @ENDNODE @NODE frageantwort "AProf: Question and Answer" o What is an 'clean' symbol table? Clean symbol tables include only function entry addresses. Neither intermediate labels are defined nor data symbols in code hunks. @ENDNODE @remark ******* @remark * Hilfeseiten für Dialoge. Aufruf erfolgt direkt aus AProf @remark * @remark * Texte werden in diesem Hilfedokument mehrfach verwendet. @remark ******* @NODE dialog-preferences "AProf: Preferences dialog" APROF: PREFERENCES DIALOG @{ " Exit help " close } ------------------------- Symbol pattern: Provide a regular expression for symbols you want to exclude from profiling. For a description of Amiga regular expressions see your dos manual. Patterns can be used to remove compiler generated intermediate labels or functions you aren't interested in. One advantage of removing functions from the symbol table is faster profiling. Example: 'L#[0-9]' removes symbols starting with an 'L' followed by any number of digits (L1 L00 L4711). Separate/Combined: (Mode) Specifies how function timing values are accumulated. If combined is selected, the time value for a function includes the times of all functions that are called by this function. Separate excludes the times of called functions. Note that if your code includes recursive procedure you must use separate mode. If combined is used, the time for the recursive procedure is wrong. See @{ "example" link gad-inex }. Millisecond/Percentual time units: (Units) Selects the units used for for timing values. If percentual is active, times shown are fractions of overall execution time in percent. Safe profiling: If safe profiling is on (selected), then while profiling, every breakpoint must pass additional tests to ensure that it belongs to a function entry or exit (See @{ "dirty symbol tables" link frageantwort }). If off, this tests are not done, resulting in faster profiling. Since it is hard to notice the time spent in doing the tests, it is recommended to activate safe profiling. Rexx Unmangler: Specifiy the filename of the Rexx procedure to be used for name unmangling. Some programming languages (eg. C++) offer 'type-safe linking', which is often implemented by coding the argument types into the symbol names (this process is called symbol mangling). Since for humans this symbol names are then hard to read, it is possible to specify a Rexx procedure for translating the symbol back in a more readable form. See @{ "example Rexx unmangler" link rexxample }. Sort order: Specify the preferred sort order. @ENDNODE @NODE rexxample "AProf: Rexx example" /* Dummy C Unmangler * * This demonstrates the basics for AProf unmanglers written in Rexx * * Don't use this in real life, since this is included in AProf * as standard unmangler (No mangler selected in preferences) * * This unmangler removes a leading '_', if one exists */ /* Get the symbol name from AProf and put it in 'symnam' */ parse arg symnam /* Check if there is a leading '_' */ if "_" = left( symnam, 1 ) then /* Remove first char */ symnam = right( symnam, length( symnam ) -1 ) /* Return result */ exit symnam @ENDNODE @NODE dialog-exec "AProf: Exec dialog" APROF: EXEC DIALOG @{ " Exit help " close } ------------------ Command line: A command line for the profilee can be specified. The command name must not be given. Example: You have written a program named 'foo', which needs one argument 'bar' to be specified on the command line. The following steps are needed to get an execution profile of 'foo': o Start AProf: aprof foo o Select 'Data...' and insert 'bar' as command line o Select 'Use' o Select 'Start' Stack size: Provide a stack size for the profilee. @ENDNODE