home *** CD-ROM | disk | FTP | other *** search
/ Power GUI Programming with VisualAge C++ / powergui.iso / trialva / ibmcppw / sdk / bin / wst.txt < prev    next >
Encoding:
Text File  |  1995-07-11  |  9.8 KB  |  280 lines
  1.  
  2.  
  3.         Microsoft Windows NT Working Set Tuner README File
  4.  
  5.                        September 04, 1994
  6.  
  7.  
  8.  
  9. 1.  Description:
  10. ----------------
  11.  
  12.     Windows NT (32-bit) Working Set Tuner (WST) for x86, Mips,
  13.         Alpha, and PowerPC platforms.
  14.  
  15.     The working set of a program is a collection of those pages in the
  16.     program's virtual address space which have recently been referenced.
  17.     As the working set size decreases, memory demand decreases.  Since
  18.     it is advantageous to minimize the memory demand, the working set
  19.     tuner DLL is developed to measure code working set, and produce an
  20.     ordering of the functions (procedures) within the code which will be
  21.     small, if not minimal, in a paging environment.  In any practical case
  22.     there are probably many optimal assignments of functions to pages.
  23.     Although this method does not claim optimality, it will produce results
  24.     at least as good as a programmer could achieve by hand in a reasonable
  25.     amount of time.  This method consists of two parts:
  26.  
  27.     1)  Data Collection:
  28.  
  29.         Data is collected in C programs by using the attributed
  30.     profiling hook provided by the Microsoft C compiler (compiling with the
  31.     "-Gh" option).  Data is not collected in assembler language programs.
  32.     A hook routine in the working set tuner DLL, WST.DLL, is called before
  33.     each C functions is called.  The hook examines its environment to
  34.     determine the identity of the called function.  A bit is set in a
  35.     bitmap every time a function is called within the specified time segment.
  36.     A new bitmap is used (new snapshot) for each new time segment: smaller
  37.     time segments will cause higher frequency of snapshots which will
  38.     produce better working set (with some diminishing point of return...).
  39.     The collected WST data is dumped upon the program's termination or via
  40.     WST's dump facility called WstDump.exe.  Functions' symbols in the
  41.     program's symbol table are used by the WST.dll to match function names
  42.     to bits in the bitmap.
  43.  
  44.     2)  Data Reduction:
  45.  
  46.         Two post-processing tools, WstCat.exe & WsTune.exe, were
  47.     developed to process the collected data and produce an ordering of the
  48.     functions (packing list) which, when placed into pages, will result
  49.     in a smaller working set of pages in memory compared to its original
  50.     working set size for the activity measured.  The packing list, created
  51.     using an ordering algorithm, can be used by the linker to perform the
  52.     actual packing within the executable's object modules.
  53.  
  54.  
  55.  
  56. 2.  WST Files:
  57. --------------
  58.  
  59.     o  wst.ini     -- WST initialization file.
  60.     o  wst.dll     -- WST DLL.
  61.     o  wst.lib     -- WST library file containing WST entry point.
  62.     o  wstdump.exe     -- Dump utility for dumping/clearing wst data, and
  63.                 stopping data collection at any time.
  64.     o  wstune.exe     -- Data analysis utility for creating the packing list
  65.                 from collected data.
  66.     o  wstcat.exe     -- Concatenation utility for multiple data files.
  67.     o  penter.lib    -- An empty library containing a dummy WST entry point.
  68.                         This can be used instead of WST.lib to link with an
  69.                 executable object module which was compiled with the
  70.                 -Gh option, so the application can run without recompiling
  71.                             and without any of the WST overheads.
  72.  
  73.  
  74.  
  75. 3.  Using the Working Set Tuner Dll:
  76. ------------------------------------
  77.  
  78.     o  Create the WST directory in the root directory of C: drive. (c:\wst)
  79.  
  80.     o  Place WST.INI in the WST directory of C: drive and list all
  81.        the DLL/EXE images to be tuned as follows:
  82.  
  83.        (Note:  WST.INI and all its three section headers must exist but the
  84.         sections could be left blank)
  85.  
  86.        [EXES]
  87.        Name of applications to be tuned. Each name should be on a
  88.        new line.
  89.  
  90.        [PATCH IMPORTS]
  91.            List of DLLs/EXEs to be tuned for all of their imported entries.
  92.            Each name should be on a new line.
  93.  
  94.        [TIME INTERVAL]
  95.        Elapsed time in milliseconds between recording snapshots
  96.        (if left blank default time interval of 1000 is used)
  97.  
  98.     o  Sample WST.INI file:
  99.  
  100.        [EXES]
  101.        myapp.exe
  102.  
  103.        [PATCH IMPORTS]
  104.  
  105.        [TIME INTERVAL]
  106.        1500
  107.  
  108.     o  Attach WST.DLL to the application process:
  109.  
  110.        -  Recompile your EXE/DLL using the "-Gh" and "-Zd" compiler
  111.           options.  (NOTE - on Mips platform, use "-Od" to disable
  112.               compiler optimization.)
  113.  
  114.  
  115.        -  Link it with WST.LIB using the "-debugtype:coff" and
  116.           "-debug:mapped,partial" linker options.
  117.  
  118.        -  This method will cause all the C functions in the recompiled
  119.           sources to be accessible to WST.DLL.
  120.  
  121.            NOTE:-  If symbols have been removed from your exe
  122.            or dll, Wst will try to locate the symbols files (DBG
  123.            files) using the path as specified in the environment
  124.            variable "_nt_symbol_path".
  125.            E.G. if the DBG file of your exe is in c:\symbols\exe, set
  126.            _nt_symbol_path to c:\symbols.
  127.  
  128.     o  Place WST.DLL in your SYSTEM directory (i.e. ..\nt\system32).
  129.  
  130.     o  If this is the only run that is to be considered for tuning, clear
  131.        any existing .TMI and .WSP files in C:\WST directory.
  132.  
  133.     o  Run your applications.
  134.  
  135.     o  Data will be collected for all the applications specified in the
  136.        [EXES] section of the WST.INI.
  137.  
  138.     o  Exit the application to dump the WST data, or run WstDump.exe
  139.        to dump the data.  See section 4 "WST Data" for details.
  140.  
  141.     o  If you have multiple TMI & WSP files, run WstCat.exe to concatenate
  142.        data from multiple runs.  See section 5 "Using WstCat" for details.
  143.  
  144.     o  Run WsTune.exe to generate the packing list (.prf file) based on
  145.        the collected WST data.  See section 6 "Using WsTune" for details.
  146.  
  147.     o  Use the packing list to direct the linker to order the modules
  148.        as specified in the packing list (.prf file).  See section 8
  149.        "Linking with the Packing List" for details.
  150.  
  151.  
  152.  
  153. 4.  WST Data:
  154. -------------
  155.  
  156.     o  WST data can be captured in two ways:
  157.  
  158.        1)  Upon termination of the application WST data is dumped
  159.            automatically.
  160.  
  161.        2)  Using the dump utility, WstDump.exe, WST data can be dumped
  162.            at any time.  See section 7 "Using WstDump" for details.
  163.  
  164.  
  165.     o  Data files are created in C:\WST directory.
  166.  
  167.     o  WST data is dumped into data files using the application and its
  168.        DLLs names with .TMI & .WSP extensions.
  169.  
  170.     o  If TMI & WSP files exist in the c:\wst directory, new data files
  171.            with .T?? and .W?? are created where ?? is a number between
  172.            0x01-0xff.  The number indicates the run number.  All the data
  173.            files can be concatenated (using WstCat.exe) to generate a single
  174.            packing list from the multiple run data files.
  175.  
  176.  
  177.  
  178. 5.  Using WstCat:
  179. -----------------
  180.  
  181.     o  WstCat.exe can be used to concatenate multiple .WSP and .TMI files
  182.        (multiple files will be named *.T00 - *.Tff and *.W00 - *.Wff)
  183.        into a single file for analysis.  This allows the user to run
  184.        multiple scenarios, over time, and analyze them as a single run.
  185.        WST will also create multiple files if a scenario exceeds its 3200
  186.        snapshots limit.
  187.  
  188.        Usage:  WstCat modulename
  189.  
  190.                 modulename is the name of the DLL or EXE which is being
  191.            tuned and data has been collected for.
  192.  
  193.        Note:  The original TMI & WSP files will be renamed to TXX & WXX
  194.               by WstCat.
  195.  
  196.  
  197.  
  198. 6.  Using WsTune:
  199. -----------------
  200.  
  201.     o  WsTune.exe is used to analyze the data created by WST.  WsTune
  202.        will also create the packing list, .PRF file, which is used by
  203.        the linker to pack your DLL or EXE.
  204.  
  205.     o  The DATA files created by wstune are:
  206.  
  207.             -  .DT (Data Tuned) contains the analysis data/bitstrings for
  208.            all api's called in the "packing list" order.
  209.  
  210.         -  .DN (Data Not tuned) contains the api's called in
  211.            the "unpacked" order.
  212.  
  213.         -  .PRF contains the packing list to be used by the linker.
  214.  
  215.         -  .WSR is a worker index file created for internal use.
  216.         
  217.  
  218.        Usage:  WsTune [/O] [/D] [/N] [?] ModuleName.WSP
  219.  
  220.            /O   Dump data to file (*.DT tuned & *.DN not tuned).
  221.            /D   Dump analysis data only (don't dump bitstrings data).
  222.            /N   Just analyze bitstring data, don't dump any data.
  223.            /?   Causes the usage message to be displayed.
  224.  
  225.  
  226.  
  227. 7.  Using WstDump:
  228. ------------------
  229.  
  230.     o  WstDump.exe can be used to stop WST data collection and clear/dump
  231.        WST collected data for all the applications being tuned, at any time.
  232.  
  233.     o  The following options are available via WstDump.exe:
  234.  
  235.           - Stop : Stops WST data collection (applications continue to run).
  236.  
  237.           - Clear and Restart : Clears any existing WST data and
  238.                     restarts data collection.
  239.  
  240.           - Dump and Stop : Dumps any existing WST data and stops the
  241.                 data collection (applications continue to run).
  242.  
  243.     o  Data is dumped to C:\WST using the application and its DLLs names
  244.            with .TMI & .WSP extensions.
  245.  
  246.     o  If TMI & WSP files exist in the C:\WST directory, new data files
  247.            with .T?? and .W?? are created where ?? is a number between
  248.            0x01-0xff.  The number indicates the run number.  All the data
  249.            files can be concatenated (using WstCat.exe) to generate a single
  250.            packing list from the multiple run data files.
  251.  
  252.  
  253.  
  254.  
  255. 8.  Linking with the Packing List:
  256. ----------------------------------
  257.  
  258.     o  Recompile your applications using the Microsoft C Compiler "-Gy"
  259.        option.  (Remove the "-Gh" option to avoid extra overhead.)
  260.  
  261.     o  Relink your applications using the link "-order:@filename" option
  262.        where filename is the name of your packing list (i.e. .prf file
  263.        generated by WsTune.exe).
  264.  
  265.  
  266.  
  267. 9.  Caveats:
  268. ------------
  269.  
  270.     o  If symbols are not available in an EXE/DLL that is being tuned,
  271.        ??? is displayed as the function name in data and analysis files
  272.        (??? is not listed in the packing list, however.)
  273.  
  274.     o  WST data is *NOT* collected for functions in assembler language
  275.        programs/objects.
  276.  
  277.  
  278.  
  279. ** END OF README **
  280.