windows-server-2003/sdktools/profile

                    Installing and Using 

                        Profile.exe

                Windows NT Sampling Profiler  





                                                    Windows NT v4.0



Overview:



The Windows NT Sampling Profiler is an easy to use tool that records

the how often each function of an application is called during the

course of that application. 





Installation:



Required Files:

    PROFILE.EXE     Windows NT Sampling Profiler

        Installed from the SDK

    PSAPI.DLL       Process Support API Library

        Installed from the SDK



Before trying to use the Sampling Profile make sure the required

files listed above are in the path. 



Use:



    Required Environment Variables:



    The Sampling profiler must have access to the image's symbols 

    in order to produce the most meaningful output. The sybmols 

    are searched in the path described by the 



        _NT_SYMBOL_PATH



    environment variable. Be sure to set this variable to the 

    correct path before attempting the profile.





    Command Line Arguments:



    Usage: profile [/a] [/innn] [/k] name-of-image [parameters]...

       /a       All hits

       /bnnn    Set profile bucket size to 2 to the nnn bytes

       /ffilename Output to filename

       /innn    Set profile interval to nnn (in 100ns units)

       /k               profile system modules

       /s[profilesource] Use profilesource instead of clock interrupt

       /S[profilesource] Use profilesource as secondary profile source



    /a 

        will display ALL hits or addresses that were sampled during 

        the test run. Normally the hits are summarized by function.



    /bnnn

        Sets the profile bucket size (in bytes) to use. The default 

        is 4 bytes. This determines the sample address granularity.



    /ffilename

        set the output file that is produced when the sampled program

        terminates. The defalt for this is "profile.out"



    /innn  

        Sets the sample interval in 100 nS units. The default value

        is 488.2 microseconds (or /i4882)



    /k

        allows processing of system functions that are called by

        the process being profiled. Normally on the the user mode

        functions of the process are profiled.



    /sprofilesource

        changes the profile sample interrupt from the clock interrupt

        to another source. This option is not supported on all 

        platforms, however.



        ALPHA Options:

            align

            totalissues

            pipelinedry

            loadinstructions

            pipelinefrozen

            branchinstructions

            totalnonissues

            dcachemisses

            icachemisses

            branchmispredicts

            storeinstructions



        MIPS options:

            align



    /Sprofilesource

        same options as above only this selects the secondary profile

        interrupt source





    Sample Command Lines:



        profile myprog.exe



            profiles the program "myprog.exe" using the default

            settings and monitoring only the user mode functions. 

            The output is written to the default filename of 

            "profile.out" in the default directory.



        profile /k /fMyProg.dat myprog.exe



            profiles the program "myprog.exe" using the default

            settings and monitoring both the user mode and the

            kernel mode functions executed by this process

            The output is written to the user specified filename

            of "MyProg.dat" in the default directory.



While the program being profiled runs, the instruction pointer is being 

sampled periodicaly and profile records the value of the instruction 

pointer each time the sample occurs inside the profiled process. When the

program terminates the recorded address values are looked up in the symbol

files to determine the function being run at the time. The tabulation 

of the results is then output to the specified, or default, filename.



The output consists of 3 comma separated fields. The first field is the 

number of times a sample occured in the function. The second field is the 

name of the module containing that function and the third field is the

name of the function within the module followed by it's virtual 

address. In a verbose listing each of these function entries is followed 

by a listing of the actual addresses that were sampled.