home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / amiga / utility / misc / spysyste.lha / SpySystem.doc < prev    next >
Encoding:
Text File  |  1992-07-05  |  15.4 KB  |  388 lines
  1.  
  2.               SPY Process Time Monitoring System
  3.               ==================================
  4.  
  5.              By Supervisor Software 1989,90,91,92
  6.  
  7.  
  8.                        Revision 2
  9.  
  10.  
  11.  
  12.  
  13. The SPY system allows one to monitor the overall CPU usage and the CPU
  14. times consumed by various tasks and processes running on the Amiga.
  15.  
  16. These new program versions are NOT compatible with the older ones.  Using
  17. different versions simultaneously may cause a system crash.
  18.  
  19.  
  20. This package consists of three different programs:
  21.  
  22. Spy v2.01    - This program loads and initializes a shared library which
  23.           contains the time monitoring routines and a few other
  24.           routines called by the tools included.  This program must
  25.           be run before any other tools can be used.
  26.  
  27. DSD v2.07    - A graphic display of CPU loading with numeric information
  28.           about the system uptime and CPU load.
  29.  
  30. Report v2.05    - A CLI utility for listing all tasks and processes in the
  31.           system and showing their CPU usage information.
  32.  
  33. TopCPU v2.05    - A new addition to Spy system.  This program currently
  34.           lists ten most CPU intensive tasks or processes and their
  35.           relative CPU usage.
  36.  
  37. CPUTime v.0.25    - A new addition to Spy system.  This program measures the
  38.           CPU time and real time consumed by any CLI program.  This
  39.           program is currently in it's beta testing phase.
  40.  
  41. sssystem.library v2.4
  42.         - This is a shared library which must be present for the
  43.           other tools to work.  This library must be initialized by
  44.           the Spy program before any timing measurements are done.
  45.           This is because it would otherwise be impossible to pass
  46.           any options to the library.
  47.  
  48.  
  49.  
  50. This package is primarly designed for the new Kickstart and Workbench 2.x,
  51. but it will also run on Kickstart 1.3, although the CPU time measurement is
  52. very inaccurate under 1.3 unless a CIA hardware timer is used (see below).
  53.  
  54. Use 'command ?' for a template, 'command ??' for human readable help or
  55. 'command ???' for full online help in any of the programs mentioned above.
  56.  
  57.  
  58.  
  59.  
  60. USAGE:
  61. ======
  62.  
  63. Spy
  64. ~~~
  65. First run Spy to load and initialize sssystem.library.  Spy will return
  66. immediately, thus no RUN command is required.  If you wish, you can later
  67. later remove Spy from the Amiga by running it again with the Remove option.
  68. Spy can only be removed from the system when no DSD/TOPCpu/CPUTime/Report
  69. programs are running.
  70.  
  71. Spy has a few command line options to control the operation of the time
  72. monitoring system.
  73.  
  74.  Install        installs Spy routines in memory (initializes the library)
  75.  Remove         removes Spy routines from memory (deintializes the library)
  76.  -Times         sets Started time to current time for all tasks
  77.  -A             uses CIAB timer A for timing
  78.  -B             uses CIAB timer B for timing
  79.  
  80. You must always specify either Install or Remove (only the upper case
  81. characters of any option are needed, so you can use I for Install and R
  82. fo Remove).
  83.  
  84. The option -Times causes all tasks and processes started _before_ Spy to
  85. receive the current time as their starting time.  That is, all processes
  86. started before Spy will look like they were started at the same time with
  87. Spy.  If this option is NOT used, the processes mentioned will have an
  88. 'unknown' starting time.
  89. All tasks and processes started _after_ Spy was run will always get the
  90. real starting time in their structures.
  91.  
  92. Options -A and -B are used to allocate a CIA B hardware timer for accurate
  93. time keeping.  If neither is used, sssystem.library will use the time in
  94. Dos library's RootNode (under Workbench 1.x) or the system ReadEClock()
  95. routine (under Workbench 2.x).
  96. It is recommended to use either -A or -B, especially under Workbench 1.x,
  97. where there is no good way of reading an accurate time from the system.
  98. An inaccurate time may cause serious timing problems with DSD, Report, and
  99. TOPCpu.
  100. Under Workbench 2.04, the accuracy of ReadEClock() is the same as that of
  101. the sssystem.library's own CIA timer routines.  However, the routines of
  102. the sssystem.library are more optimized and result in slightly better
  103. overall performance.  If both CIA B timers are needed by other programs,
  104. the options can be left out and the system's ReadEClock() used instead.
  105.  
  106.  
  107.  
  108. DSD
  109. ~~~
  110. You may start DSD right after running Spy.  The initial x and y coordinates
  111. for the DSD window can be specified on the command line.  For example,
  112. DSD -x400 -y0 sets the coordinates to (400,0).  Specifying coordinates of -1
  113. will open the window as far right and down as possible.
  114.  
  115. Normally DSD updates its display once a second.  The user can specify a
  116. different interval time (1...3600 seconds) using the -Interval option:
  117.  
  118. DSD -I60
  119.  
  120. sets the interval to 60 seconds.
  121.  
  122. DSD may be terminated at any moment by clicking its close gadget or sending
  123. a CTRL+C signal to it.
  124.  
  125. The DSD display shows the CPU usage (load) in graphical form.  When the
  126. graph is low, the CPU load is low.  When the CPU is fully loaded, the graph
  127. will fill the entire display.  The graph is updated once every <interval>
  128. seconds, thus the approximate timing of load peaks can also be determined.
  129.  
  130. The Load numbers show the CPU loading.  100% means the CPU is fully loaded.
  131. The number on the left hand side shows the value for the last seconds, the
  132. other shows the CPU load calculated for the total Uptime.
  133.  
  134. IdleCPU shows the total amount of time that CPU has been idle (ie. it has
  135. had nothing to do) and Uptime shows the time that the SPY system has been
  136. running (usually Spy is started during machine boot so this will show the
  137. total uptime of the Amiga).
  138.  
  139.  
  140.  
  141. Report
  142. ~~~~~~
  143. Report is a CLI based utility used to list all tasks and processes running
  144. on the Amiga.  It shows many kinds of information about the tasks:
  145.  
  146. FIRST, it lists the Uptime, IdleCPU and Average Load:
  147.  
  148. Uptime:  0 00:23:15.140    Idle CPU:  0 00:21:04.494    Average Load:   9.39%
  149.  
  150. THEN, it lists all tasks and processes in alphabetical order:
  151.  
  152. num taskname (args)        typ  id  pri task ptr stack  used  disp   CPU time
  153.   1 AmiCron                 bw   4    0 078C1C68  8192   314   204      0.339
  154.   2 bin/keylock             bw   2    0 078AFAF8  8192   118     0      0.000
  155.   3 CD0                     pw       10 0788C648  6000   182  2306      0.781
  156.   4 CON                     pw        5 07901C18  3200   530     0      0.000
  157.   5 CON                     pw        5 0790B220  3200   530     0      0.000
  158.   6 CON                     pw        5 078DCE70  3200   530     0      0.000
  159.   7 CON                     pw        5 07871C50  3200   530    16      0.059
  160.   8 console.device          tw        5 0780E160  4096    90    68      0.460
  161.   9 CON                     pw        5 078E5E48  3200   530   544      6.959
  162.  10 DF0                     pw       10 07815B40  2400   130     0      0.000
  163.  11 DF2                     pw       10 078352A0  2400   130     0      0.000
  164.  12 DH0                     pw       10 07817FC0  2400   130   577      0.160
  165.  13 DH1                     pw       10 078379C0  2400   130   800      0.340
  166.  14 DH2                     pw       10 0783D708  2400   130    54      0.000
  167.  15 dsd                     bw   5    0 078E30C8  8192   152  1196      8.062
  168.  16 Enhancer v1.577         pw       10 07883988  8192    94    61      0.000
  169.  17 H0                      pw       10 078230C0  2400   130    10      0.000
  170.  18 H1                      pw       10 07829150  2400   130     0      0.000
  171.  19 H2                      pw       10 0782F1F0  2400   130     0      0.000
  172.  .. ..                      ..       .. ........  ....   ...     .      .....
  173.  .. ..                      ..       .. ........  ....   ...     .      .....
  174.  .. ..                      ..       .. ........  ....   ...     .      .....
  175.  
  176.  
  177. If ssystem.librayry is not active, the timing information for tasks and
  178. processes is not available.  In that case, the appropriate fields of output
  179. will be blank.
  180.  
  181.  
  182. The meanings of the colunms are:
  183.  
  184. num        Line number of printout (may be disabled with option
  185.         -NONumbers)
  186.  
  187. taskname    Name of task or process shown.  Under Workbench 2.0, the
  188.         command line arguments of CLI commands are also shown.
  189.  
  190. typ        Task or process type: First letter indicates if this is a
  191.         CLI background process (b), a process (p) or a simple task
  192.         (t).  Second letter shows if this task or process is doing
  193.         nothing (waiting, w) or currently ready to run (ready, r).
  194.  
  195. id        CLI identifier number.
  196.  
  197. pri        Priority (-128...+127) of this task or process.
  198.  
  199. task ptr    Task structure pointer of this task or process.
  200.  
  201. stack        Stack size for this task or process.
  202.  
  203. used        This many bytes of stack are in use.
  204.  
  205. disp        Number of dispatches for this task or process (shows how
  206.         many times this task has been scheduled to run or how many
  207.         times it has needed CPU time).
  208.  
  209. CPU time    CPU time used by this task or process, shown in seconds and
  210.         milliseconds (or seconds only when the value exceeds 1000000
  211.         seconds).  This field is not reliable under WB 1.3 for the
  212.         current version of Spy without a CIA timer (see below).
  213.  
  214. created        (Not shown above) Time when this task or process was
  215.         started.  This may be unknown for the tasks that were
  216.         launched before Spy was started (unless -Times option is
  217.         used for Spy).
  218.  
  219. idle        (Not shown above) Time which the task or process has been
  220.         sleeping, needing no CPU time.  If a CLI window or an
  221.         application program is not used, it usually needs no CPU
  222.         time and the idle time is seen here.  Most system processes
  223.         need CPU time several times a second and this field is
  224.         blank (meaning no idle time for that process).
  225.  
  226. sigalloc    (Not shown above) The task signal bits allocated by this
  227.         task or process.
  228.  
  229. sigwaitf    (Not shown above) The signal bits this task or process is
  230.         currently waiting for.
  231.  
  232. sigexcpt    (Not shown above) The signal bits on which this task or
  233.         process will execute an exception routine.
  234.  
  235. sigrecvd    (Not shown above) The signal bits received by the task or
  236.         process.
  237.  
  238.  
  239. Report has several command line options:
  240.  
  241. [<pattern>|$<address>|#<cli_id>] [-Time] [-Format="<fmtchars>"]
  242. [-Header[="<header>"]] [-NOHeader] [-[NO]Status] [-[NO]Numbers]
  243. [-CLI] [-Proc] [-SIgnals] [-TAsk] [-Waiting] [-Ready] [-Unix]
  244.  
  245. The characters shown in UPPER CASE are obligatory, while those in lower
  246. case are optional.  Option strings are case-insensitive.  Thus, -H, -He,
  247. -HEA and -HeAdEr mean all the same option.
  248.  
  249. When <pattern> is specified, Report only lists tasks and processes whose
  250. names match the given pattern string.  Under Workbench 2.x, the standard
  251. AmigaDOS wildcards can be used.  Under 1.3, if the pattern string ends with
  252. an asterisk (*) all task and process names beginning with the given
  253. string will be listed.
  254.  
  255. When $<address> is specified, Report will only list one task with the
  256. Task structure pointer of <address>.  The address mus be given in
  257. hexadecimal as shown in the task ptr field of Report output.  If a given
  258. task is not found, No match will be printed instead of the task's data.
  259.  
  260. When #<cli_id> is specified, Report will only list one CLI process
  261. with the given CLI id number.  The id must be a decimal number.  If a given
  262. process is not found, No match will be printed.
  263.  
  264. -Time option selects the alternate output format of Report, showing the
  265. task starting and idle times instead of some other information.
  266.  
  267. -Format option can be used to specify a custom output format.  <fmtchars>
  268. may contain nay combination of the following formatting characters:
  269.  
  270.  %n    task name and arguments (shorter format, 22 columns)
  271.  %N    task name and arguments (longer format, 30 columns)
  272.  %t    task or process type
  273.  %c    CLI process id
  274.  %p    priority
  275.  %a    address of Task structure
  276.  %s    stack size and usage
  277.  %d    number of dispatches
  278.  %T    CPU time consumed, long format
  279.  %H    CPU time consumed, short format (hh:mm)
  280.  %C    creation time of task or process
  281.  %i    idle tile of task or process
  282.  %S    task signal bits
  283.  
  284. The default format string is "%n %t %c %p %a %s %d %T" and the -Time format
  285. is "%n %t %c %a   %d %T %C %i".
  286.  
  287. -Header enables the header line for printing.  If -Header="<header>" is
  288. specified, the custom header line will be used instead of the standard
  289. one.  The header line can be set in the environment variable (see below).
  290. -NOHeader and -Header control the printing of header.  By default, the
  291. header line is printed unless only one task or process is listed.  For
  292. every -NOHeader, one -Header must be given to reverse the option's effect.
  293.  
  294. -NONumbers and -Numbers control the printing of line numbers.  By default,
  295. the numbers are printed unless only one task or process is listed.  For
  296. every -NONumbers, one -Numbers must be given to reverse the option's effect.
  297.  
  298. -NOStatus and -Status control the printing of status line.  By default, the
  299. status line is printed unless only one task or process is listed.  For
  300. every -NOStatus, one -Status must be given to reverse the option's effect.
  301.  
  302. -CLI causes only CLI processes to be printed.
  303. -TAsk causes only tasks to be printed.
  304. -Proc causes only non-CLI processes to be printed.
  305. If several flags are specified, all the specified task types will be printed.
  306. By default, all types of tasks and processes are printed.
  307.  
  308. -Ready filters all waiting (idle) processes off the printing causing only
  309. ready processes to be printed.  -Waiting only prints processes which are
  310. sleeping at the moment.  These flags are mutually exclusive.  By default,
  311. all tasks and processes are printed recardless of their state.  These flags
  312. can not be set in the environment variable.
  313.  
  314. -Signals lists the states of task's signal bits (found in the Task structure).
  315.  
  316. Options for the Report command can be given in an environment variable
  317. called 'report'.  The command line options can be used to override the
  318. defaults or the ones set by the environment variable when needed.
  319.  
  320.  
  321.  
  322. TopCPU
  323. ~~~~~~
  324. TopCPU has similar options as DSD.  TopCPU shows ten most CPU intensive
  325. tasks or processes and the relative CPU times (percents) in both numeric
  326. and graphical format.
  327.  
  328. You may start TopCPU right after running Spy.  The initial x and y
  329. coordinates for the TopCPU window can be specified on the command line.
  330. For example, TopCPU -x0 -y200 sets the coordinates to (0,200).  Specifying
  331. coordinates of -1 will open the window as far right and down as possible.
  332.  
  333. Normally TopCPU updates its display every five seconds.  The user can
  334. specify a different interval time (0.1 to 60.9 seconds) using the -Interval
  335. option:
  336.  
  337. TopCPU -I0.5
  338.  
  339. sets the interval to 0.5 seconds.  Using shorter interval times increases
  340. the CPU load caused by TopCPU due to more frequent display updates.
  341.  
  342. TopCPU may be terminated at any moment by clicking its close gadget or
  343. sending a CTRL+C signal to it.
  344.  
  345. TopCPU lists ten tasks or processes getting most of the CPU time at a
  346. time.  The calculation is done for the whole -Interval time; for example,
  347. with the default interval of five seconds, a task which has gotten 60% of
  348. the CPU time has consumed (60/100)*5 seconds or 3 seconds of CPU time.
  349.  
  350.  
  351.  
  352. CPUTime
  353. ~~~~~~~
  354. CPUTime measures the real and CPU time used by a given CLI command like
  355. a compiler or a sort program.  The only arguments needed by CPUTime are
  356. the command to be run and its arguments.
  357.  
  358. CPUTime CLI-command arguments
  359.  
  360. Only the CPU time used by <CLI-command>'s process is measured.  If the
  361. command outputs text or uses other file-I/O, the CPU time consumed by
  362. the console window processes etc. is NOT taken into account.
  363.  
  364. CPUTime currently uses Execute() routine to launch the commands.  This
  365. may change in the future.
  366.  
  367.  
  368.  
  369. Other
  370. ~~~~~
  371. These programs are still under development.  Feel free to send bug reports
  372. or suggestions to the author.
  373.  
  374. Thank you for your interest.
  375.  
  376. Supervisor Software
  377.  
  378.  
  379.  
  380. Mail:                     E-Mail:                  Voice/FAX:
  381.  
  382.   Jukka Marin               jmarin@messi.uku.fi      int. + 358 71 232 793
  383.   Metsurintie 17 B 8
  384.   70150 Kuopio
  385.   FINLAND
  386.  
  387.  
  388.