home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / programming / swistat / !SWIstat / !Help next >
Text File  |  1995-07-16  |  14KB  |  277 lines
  1.  
  2.  
  3.                         SoftWare Interrupt Statistics
  4.                         =============================
  5.  
  6.  
  7. Documentation for !SWIstat application version 2.01 01-May-1995
  8. for RISC OS 3.1 and later.
  9.  
  10. Issue: 2.01/T  17-Jun-1995, replaces:   0.10    21-Aug-1990
  11.                                         1.00    01-Sep-1990
  12.                                         1.00/R  21-Jun-1991
  13.                                         1.01/R  24-Apr-1992
  14.                                         1.50    05-Apr-1994
  15. Author: David J Ruck
  16.  
  17. Copyright © DEEJ Technology PLC 1990-1995 
  18.  
  19.  
  20. Overview
  21. ========
  22.  
  23. The !SWIstat application provides information on the activity of all SoftWare 
  24. Interrupts (SWI's) occurring in your machine, the next best thing to Acorns 
  25. own hardware debugging systems.
  26.  
  27. It is intended for programmers who wish to debug or improve the efficiency
  28. of  their application's or module's interface with the OS. It does this by
  29. showing  exactly which software interrupt calls are being made, when and in
  30. what  quantity.
  31.  
  32. It can also be used by the merely incurably curious for a fascinating
  33. insight  into  what the computer is getting up to, and which are the most
  34. frequently  used SWI's.
  35.  
  36.  
  37.  
  38. Using !SWIstat
  39. ==============
  40.  
  41. When started !SWIstat installs its own icon on the icon bar, clicking on it
  42. will  display the main window. This window contains information on all the 
  43. currently installed modules in the machine.
  44.  
  45. Each module that provides SWI's  has its own entry, giving its name and a 
  46. value and a graphic display of this value, similar to the bars used in the
  47. Task  manager's window.
  48.  
  49. The value is either the total number of SWI calls handled by modules since
  50. the  application was first installed in the machine, or the number of calls
  51. handled in  a set time period. Switching between these displays is described
  52. in the  !SWIstat menu section below.
  53.  
  54. The Main Window The first entry in the window is the total value of all the
  55.                 entries below. The utility module SWI's have been split into
  56.                 two sections; the first for SWI's in the range 000000 Hex to
  57.                 0000FF Hex and the second for OS_WriteI's from 000100 Hex to 
  58.                 0001FF Hex, All SWI's referred to include the X form.
  59.  
  60. Sub Windows     Clicking on any of the module names (not the All SWI'S entry)
  61.                 will display a subwindow for that module. The contents of the 
  62.                 window are similar to that of the main window, except that
  63.                 the number of calls (totals or per interval) for each SWI 
  64.                 that the module provides are displayed.  The first entry is
  65.                 the total for that module, as is displayed in the main window.
  66.                 
  67.                 Each of the windows for the two Utility module sections have
  68.                 256 entries, other modules have up to 64, but only SWI's
  69.                 which the module provides names for are displayed. The names 
  70.                 in the subwindows are the names of the SWI's that the module 
  71.                 provides with module name prefix removed so that more of the 
  72.                 name can be displayed.  
  73.  
  74. Counter Windows Clicking on the All SWI's entry in the main window or any
  75.                 entry in a subwindow will call up a counter window, (it
  76.                 resembles the X windows program xload).
  77.                 
  78.                 The counter window shows the number of SWI's (for an
  79.                 individual SWI or all SWI's in a module) occurring in the set
  80.                 interval, as a vertical line. The display scrolls to the left
  81.                 each interval to show a new value, thus the variation in
  82.                 activity of a SWI or module can be monitored over a period of
  83.                 time.
  84.                 
  85.                 It is easier to see sudden peaks of activity in a counter
  86.                 window than in the main and subwindows, which do not need to
  87.                 be open once a counter window has been called up. Any number
  88.                 of counter windows (memory permitting) can be active at once.
  89.                 
  90.                 The counter window display automatically scales up and down
  91.                 to fit the maximum value in the window. At the default scale
  92.                 4 OS units (1 rectangular pixel) is equivalent to one call, 
  93.                 each subsequent scale is half the last shown by the
  94.                 horizontal grey lines. These do not represent values but
  95.                 show how many times the height of the bars have been halved;
  96.                 e.g. 1 line = ½ scale, 2 lines = ¼ scale, 10 lines 1/1024th
  97.                 scale.
  98.  
  99.  
  100. Window menu 
  101. -----------
  102. The main window and all subwindows provide a menu, the entries are 
  103. described below.
  104.  
  105. Totals          This affects the main window and all subwindows. When ticked
  106.                 the display of each window gives the total number of calls to
  107.                 each SWI or module since the program was first installed. The
  108.                 dark grey backed heading of each window will change to show;
  109.                 Total SWI calls since initialisation.
  110.                 
  111. Per interval    This also affects the main window and all subwindows; it 
  112.                 changes the displays to show the number of SWI calls in a 
  113.                 given time interval, set by Update rate below. The headings 
  114.                 change to SWI calls per rate (actual rate) ms. Where rate is 
  115.                 the set rate and actual rate is the rate achieved, see below.
  116.                 
  117. Update rate     The value entered into the writable sub menu determines the 
  118.                 interval used when displaying in Per interval mode, and the 
  119.                 update rate of counter windows, which always show the number 
  120.                 of SWI's in this interval in both Totals and Per interval 
  121.                 modes.
  122.                 
  123.                 The value entered is in milliseconds (1/1000th sec), due to 
  124.                 RISC OS limitations it is only possible to set the rate to 
  125.                 the nearest 10ms, a minimum of 100ms is imposed. When using 
  126.                 large values it should be noted that the new value only 
  127.                 comes into effect on the next scheduled update.
  128.                 
  129.                 If a lot of tasks are running or a number of subwindows or 
  130.                 counter windows are open it may not be possible for the 
  131.                 program to update its displays at very high rates, this is 
  132.                 automatically taken into account, and the values and sizes of 
  133.                 bars are corrected accordingly.
  134.  
  135. Scale           Bars in the main and subwindows are automatically scaled to 
  136.                 fit the largest in the window by default, this can however, 
  137.                 lead to the bars for small values disappearing. Clicking on 
  138.                 the Scale option on the main menu toggles automatic and 
  139.                 manual scaling, which is shown by a tick next to scale.
  140.  
  141.                 When using manual scaling values can be entered in the 
  142.                 writable submenu, the top entry multiplies the size of the 
  143.                 bar, and the bottom entry divides it. Some multipliers are 
  144.                 not allowed when values becomes very large, to prevent 
  145.                 integer overflow.
  146.                 
  147. Tasks           !SWIstat monitors the SWI activity of all active RISC OS 
  148.                 tasks as default. By using the task menu, the activity of a 
  149.                 particular task can be monitored in isolation, by choosing 
  150.                 it’s name from the task list. This makes it easier to 
  151.                 scrutinise the calls made by a task which is currently under
  152.                 test.
  153.                 
  154.                 As !SWIstat must make a number of SWI calls itself in order 
  155.                 to update the displays, the activity of all tasks Except 
  156.                 !SWIstat can be shown using this option. The All Tasks entry 
  157.                 will restore the default behaviour.
  158.  
  159. Zero Counts     This option will zero the counts for all SWI’s which can be
  160.                 seen when displaying totals. All counter windows are also 
  161.                 cleared. This option can be used after changing the task 
  162.                 being monitored using the Tasks menu described above. 
  163.                 This will clear the totals so that only calls from the 
  164.                 particular task are displayed subsequently.
  165.  
  166.  
  167. Iconbar menu
  168. ------------
  169. Info            Displays program information and version number.
  170.  
  171. Display         Displays the main window, equivalent to clicking on the
  172.                 !SWIstat icon.
  173.                 
  174. Reinit          If you or an application install more SWI providing modules 
  175.                 after the !SWIstat application has started, they will not be 
  176.                 recognised unless the ReInit option is used. This resets the 
  177.                 totals since initialisation to zero, closes all subwindows 
  178.                 and counter windows, and re-displays the main window with 
  179.                 the new modules.
  180.                 
  181. Kill            Quits the application and kills the SWImod module which 
  182.                 performs the counting of SWI’s. This ensures the small 
  183.                 processing overhead imposed by the module is removed.
  184.  
  185. Quit            Quits the application, the SWImod module is not killed so 
  186.                 if the program is run again, the SWI totals will still have 
  187.                 been incremented while the program was not running, see 
  188.                 Technical details below.
  189.  
  190.  
  191.  
  192. Technical details
  193. =================
  194.  
  195. !SWIstat works by installing a special module SWImod which claims the SWI 
  196. vector. The details below are provided for users who may wish to use this 
  197. module in their own programs.
  198.  
  199. On initialisation the SWImod module interrogates each module in turn to 
  200. determine whether it provides SWI's, if it does a piece of RMA workspace is 
  201. claimed to store the total number of calls to each SWI. It then claims the
  202. SWI  vector and increments the correct value every time a SWI is called. The
  203. SWImod module is controlled using the following SWI’s.
  204.  
  205. SWI_stat (&49080)       !SWIstat uses this call every update interval to read
  206.                         the current SWI use counts, and calculate the correct
  207.                         values for the program displays.
  208.                         
  209.                         A call to SWI_stat (no parameters required) returns a
  210.                         pointer in R0 to a memory structure (type: main_str)
  211.                         which is described in C as:
  212.  
  213.     typedef struct
  214.     {
  215.         struct mod__str *chain_ptr;       /* pointer to chain of mod_str    */
  216.         int              swi_total;       /* total of all SWI’s called      */
  217.         int              totals[2];       /* total of 1st & 2nd 256 SWI’s   */
  218.         int              counts[512];     /* usage counts for 1st 512 SWI’s */
  219.     } main_str;
  220.  
  221.     typedef struct mod__str
  222.     {
  223.         struct mod__str *next_ptr;        /* pointer to next in chain       */
  224.         int              chunk_no;        /* chunk number of module         */
  225.         int              mod_total;       /* total of all SWI’s by module   */
  226.         char             mod_name[24];    /* name of module                 */
  227.         int              counts[64];      /* usage counts for 64 mod SWI’s  */
  228.     } mod_str;
  229.  
  230.  
  231. SWI_Zero (&49081)       Calling this routine causes all the SWI counts to be
  232.                         zeroed. Counting continues immediately.
  233.  
  234. SWI_Control (&49082)    This call is used to activate (R0 = 1) or suspend
  235.                         (R0 = 0) the modules counting activity. While
  236.                         suspended the SWI vector is still claimed, but
  237.                         computational overhead of the counting operation
  238.                         is removed.
  239.  
  240. SWI_Filter (&49083)     This call controls which tasks are monitored by 
  241.                         SWImod. The value of R0 are R1 control the operation.
  242.                         
  243.                         R0 = 0  All tasks are monitored (default).
  244.                         R0 = 1  R1 = task handle to exclusively monitor.
  245.                         R0 = 2  R1 = task handle to exclude,
  246.                                 i.e. monitor all except R1.
  247.                                 
  248.                         The monitoring of tasks is performed using a WIMP
  249.                         post–filter mechanism, to enable or disable the
  250.                         counting of SWI’s depending on the task the WIMP
  251.                         has just switched in. Calls made by the operating 
  252.                         system during a WIMP_Poll are assigned to the task 
  253.                         which called it.
  254.  
  255.  
  256.  
  257. !APPstat
  258. ========
  259.  
  260. Also from DEEJ Technology PLC is the companion application !APPstat.  Using
  261. the same style of displays !APPstat provides microsecond accurate  timing
  262. information on the amount of processing performed by each  application.
  263.  
  264. It is the best tool currently available to help programmers to see the
  265. results of  optimising various parts of their programs, and to decide how
  266. much time  should be spent in Idle processing, without being antisocial to
  267. other  applications.
  268.  
  269. It also provides information and timings on the event types and message
  270. action  types from Wimp_Poll's which are currently being delivered to
  271. different  tasks, so the parts of a program taking up execution time can be
  272. identified.
  273.  
  274.  
  275.  
  276. End of SWIstat User Guide.
  277.