Source code of Windows XP (NT5)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

301 lines
11 KiB

  1. Microsoft Windows NT Working Set Tuner README File
  2. April 15, 1998
  3. 1. Description:
  4. ----------------
  5. Windows NT (32-bit) Working Set Tuner (WST) for x86, Mips,
  6. Alpha, and PowerPC platforms.
  7. The working set of a program is a collection of those pages in the
  8. program's virtual address space which have recently been referenced.
  9. As the working set size decreases, memory demand decreases. Since
  10. it is advantageous to minimize the memory demand, the working set
  11. tuner DLL is developed to measure code working set, and produce an
  12. ordering of the functions (procedures) within the code which will be
  13. small, if not minimal, in a paging environment. In any practical case
  14. there are probably many optimal assignments of functions to pages.
  15. Although this method does not claim optimality, it will produce results
  16. at least as good as a programmer could achieve by hand in a reasonable
  17. amount of time. This method consists of two parts:
  18. 1) Data Collection:
  19. Data is collected in C programs by using the attributed profiling
  20. hook provided by the Microsoft C/C++ Compiler (compiling with the "-Gh"
  21. option). Data is not collected in assembler language programs. A hook
  22. routine in the working set tuner DLL, WST.DLL, is called before each
  23. C/C++ function is called. The hook examines its environment to
  24. determine the identity of the called function. A bit is set in a
  25. bitmap every time a function is called within the specified time segment.
  26. A new bitmap is used (new snapshot) for each new time segment: smaller
  27. time segments will cause higher frequency of snapshots which will
  28. produce better working set (with some diminishing point of return...).
  29. The collected WST data is dumped upon the program's termination or via
  30. WST's dump facility called WstDump.exe. Functions' symbols in the
  31. program's symbol table are used by the WST.dll to match function names
  32. to bits in the bitmap.
  33. 2) Data Reduction:
  34. Two post-processing tools, WstCat.exe & WsTune.exe, process the
  35. collected data and produce an ordering of the functions (packing list)
  36. which, when placed into pages, will result in a smaller working set of
  37. pages in memory compared to its original working set size for the
  38. activity measured. The packing list, created using an ordering
  39. algorithm, can be used by the linker to perform the actual packing
  40. within the executable's object modules.
  41. 2. WST Files:
  42. --------------
  43. o wst.ini -- WST initialization file.
  44. o wst.dll -- WST DLL.
  45. o wst.lib -- WST library file containing WST entry point.
  46. o wstdump.exe -- Dump utility for dumping/clearing WST data, and
  47. stopping data collection at any time.
  48. o wstune.exe -- Data analysis utility for creating the packing list
  49. from collected data.
  50. o wstcat.exe -- Concatenation utility for multiple data files.
  51. o penter.lib -- An empty library containing a dummy WST entry point.
  52. This can be used instead of WST.lib to link with an
  53. executable object module which was compiled with the
  54. -Gh option, so the application can run without
  55. recompiling and without any of the WST overhead.
  56. 3. Using the Working Set Tuner Dll:
  57. ------------------------------------
  58. o Create the WST directory in the root directory of C: drive. (c:\wst)
  59. o Place WST.INI in the WST directory of C: drive and list all
  60. the DLL/EXE images to be tuned as follows:
  61. NOTE:- WST.INI must exist for WST to run.
  62. [EXES]
  63. Name(s) of module(s) to be tuned. Each name should be on a new
  64. line. A semicolon ';' in front of a name removes it from the
  65. list.
  66. [PATCH IMPORTS]
  67. obsolete - no longer used
  68. [TIME INTERVAL]
  69. Elapsed time in milliseconds between recording snapshots
  70. (if left blank, a default time interval of 1000 is used).
  71. This section may include an optional entry 'MaxSnaps=n',
  72. where n is the maximum number of snapshots to take
  73. (the default maximum is 3200).
  74. o Sample WST.INI file:
  75. [EXES]
  76. myapp.exe
  77. [TIME INTERVAL]
  78. 1500
  79. MaxSnaps=256
  80. o Attach WST.DLL to the application process:
  81. - Recompile your EXE/DLL using the "-Gh" and "-Zi" or "-Z7"
  82. compiler options. (NOTE - on Mips platform, use "-Od" to
  83. disable compiler optimization.)
  84. - Link it with WST.LIB using the options "-debug", either
  85. "-debugtype:coff" or "-debugtype:both", and "-pdb:none"
  86. or "-pdb:<filename>".
  87. - This method will cause all the C functions in the recompiled
  88. sources to be accessible to WST.DLL.
  89. NOTE:- The win32.mak file in the Win32 SDK will set these
  90. options correctly for your application if you build it with
  91. the tune=1 switch. I.e. "nmake -all tune=1".
  92. NOTE:- If symbols have been removed from your exe or dll,
  93. WST will try to locate the symbols files (DBG or PDB
  94. files) in the current directory, then in the path specified
  95. by the environment variables "_nt_symbol_path",
  96. "_nt_alt_symbol_path", and "systemroot", in that order.
  97. E.G. if the DBG file of your exe is in c:\symbols\exe, set
  98. _nt_symbol_path to c:\symbols.
  99. o Place WST.DLL in your SYSTEM directory (i.e. ..\nt\system32) or in
  100. the same directory with the application being tuned.
  101. o If this is the only run that is to be considered for tuning, clear
  102. any existing .TMI and .WSP files in the C:\WST directory.
  103. o Run your application(s).
  104. o Data will be collected for all the modules specified in the [EXES]
  105. section of the WST.INI.
  106. o Exit the application to dump the WST data, or run WstDump.exe to
  107. dump the data. See section 4 "WST Data" for details.
  108. o If you have multiple TMI & WSP files, run WstCat.exe to concatenate
  109. data from multiple runs. See section 5 "Using WstCat" for details.
  110. o Run WsTune.exe to generate the packing list (.prf file) based on
  111. the collected WST data. See section 6 "Using WsTune" for details.
  112. o Use the packing list to direct the linker to order the modules
  113. as specified in the packing list (.prf file). See section 8
  114. "Linking with the Packing List" for details.
  115. 4. WST Data:
  116. -------------
  117. o WST data can be captured in two ways:
  118. 1) Upon termination of the application WST data is dumped
  119. automatically.
  120. 2) Using the dump utility, WstDump.exe, WST data can be dumped
  121. at any time. See section 7 "Using WstDump" for details.
  122. o Data files are created in C:\WST directory.
  123. o WST data is dumped into data files using the application and its
  124. DLLs names with .TMI & .WSP extensions. No data is dumped for
  125. modules which lack symbol information in the COFF format.
  126. o If TMI & WSP files exist in the c:\wst directory, new data files
  127. with .T?? and .W?? are created where ?? is a number between
  128. 0x01-0xff. The number indicates the run number. All the data
  129. files can be concatenated (using WstCat.exe) to generate a single
  130. packing list from the multiple run data files.
  131. 5. Using WstCat:
  132. -----------------
  133. o WstCat.exe can be used to concatenate multiple .WSP and .TMI files
  134. (multiple files will be named *.T00 - *.Tff and *.W00 - *.Wff)
  135. into a single file for analysis. This allows the user to run
  136. multiple scenarios, over time, and analyze them as a single run.
  137. WST will also create multiple files if a scenario exceeds its
  138. snapshots limit.
  139. Usage: WSTCAT moduleName
  140. "moduleName" is the name of the module to combine.
  141. The module is the name of the DLL or EXE which is being
  142. tuned and data has been collected for.
  143. NOTE:- The original TMI & WSP files will be renamed to TXX & WXX
  144. by WstCat.
  145. 6. Using WsTune:
  146. -----------------
  147. o WsTune.exe is used to analyze the data created by WST. WsTune
  148. will also create the packing list, .PRF file, which is used by
  149. the linker to pack your DLL or EXE.
  150. o The DATA files created by wstune are:
  151. - .DT (Data Tuned) contains the analysis data/bitstrings for
  152. all api's called in the "packing list" order.
  153. - .DN (Data Not tuned) contains the api's called in
  154. the "unpacked" order.
  155. - .PRF contains the packing list to be used by the linker.
  156. - .WSR is a worker index file created for internal use.
  157. Usage: WSTUNE [/O] [/D] [/N] [?] moduleName1[.WSP] [...]
  158. /O Dump analysis data to file (*.DT tuned, *.DN not tuned)
  159. /N Analyze bitstring data only, create .WSR and .PRF files
  160. (turns off /O)
  161. /D Dump analysis data only; use existing .WSR file (turns
  162. off /N)
  163. /P Display a progress indicator
  164. /? Display this usage message
  165. where "moduleNameX" is the name(s) of the module file(s) to tune.
  166. Each module file will result in a separate set of tuning data
  167. based on the input switch settings. If neither /O nor /N are
  168. specified, tuning data (normally the contents of the .DT file) is
  169. dumped to the standard output device.
  170. 7. Using WstDump:
  171. ------------------
  172. o WstDump.exe can be used to stop WST data collection and clear/dump
  173. WST collected data for all the applications being tuned, at any time.
  174. o The following options are available via WstDump.exe:
  175. - Stop : Stops WST data collection (applications continue to run).
  176. - Clear and Restart : Clears any existing WST data and restarts
  177. data collection.
  178. - Dump and Stop : Dumps any existing WST data and stops the data
  179. collection (applications continue to run).
  180. o Data is dumped to c:\wst using the names of the application and its
  181. DLLs with .TMI & .WSP extensions. No data is dumped for modules with
  182. no symbols.
  183. o If TMI & WSP files exist in the c:\wst directory, new data files
  184. with .T?? and .W?? are created, where ?? is a number between
  185. 0x01-0xff. The number indicates the run number. All the data
  186. files can be concatenated (using WstCat.exe) to generate a single
  187. packing list from the multiple run data files.
  188. 8. Linking with the Packing List:
  189. ----------------------------------
  190. o Recompile your applications using the Microsoft C/C++ Compiler's
  191. "-Gy" option. (Remove the "-Gh" option to avoid extra overhead.)
  192. o Relink your applications using the link "-order:@filename" option
  193. where filename is the name of your packing list (i.e. .prf file
  194. generated by WsTune.exe).
  195. 9. Caveats:
  196. ------------
  197. o If a symbol is not available in an EXE/DLL that is being tuned,
  198. ??? is displayed as the function name in data and analysis files
  199. (??? is not listed in the packing list, however.)
  200. o WST data is *NOT* collected for functions in assembler language
  201. programs/objects.
  202. o The linker currently will not reorder static functions. The
  203. Microsoft C/C++ Compiler automatically generates certain static
  204. functions (their names look like "_$Ennn", where nnn is a number
  205. the compiler assigns internally).
  206. ** END OF README **