

                        SoftWare Interrupt Statistics
                        =============================


Documentation for !SWIstat application version 2.20 11-Apr-2020
for RISC OS 3.1 and later.

Issue: 2.20  11-Apr-2020, replaces:   0.10    21-Aug-1990
                                      1.00    01-Sep-1990
                                      1.00/R  21-Jun-1991
                                      1.01/R  24-Apr-1992
                                      1.50    05-Apr-1994
                                      2.01    01-May-1995
Author: David J Ruck

Copyright  DEEJ Technology PLC 1990-1995 


Overview
========

The !SWIstat application provides information on the activity of all SoftWare 
Interrupts (SWI's) occurring in your machine, the next best thing to Acorns 
own hardware debugging systems.

It is intended for programmers who wish to debug or improve the efficiency
of  their application's or module's interface with the OS. It does this by
showing  exactly which software interrupt calls are being made, when and in
what  quantity.

It can also be used by the merely incurably curious for a fascinating
insight  into  what the computer is getting up to, and which are the most
frequently  used SWI's.



Using !SWIstat
==============

When started !SWIstat installs its own icon on the icon bar, clicking on it
will  display the main window. This window contains information on all the 
currently installed modules in the machine.

Each module that provides SWI's  has its own entry, giving its name and a 
value and a graphic display of this value, similar to the bars used in the
Task  manager's window.

The value is either the total number of SWI calls handled by modules since
the  application was first installed in the machine, or the number of calls
handled in  a set time period. Switching between these displays is described
in the  !SWIstat menu section below.

The Main Window The first entry in the window is the total value of all the
                entries below. The utility module SWI's have been split into
                two sections; the first for SWI's in the range 000000 Hex to
                0000FF Hex and the second for OS_WriteI's from 000100 Hex to 
                0001FF Hex, All SWI's referred to include the X form.

Sub Windows     Clicking on any of the module names (not the All SWI'S entry)
                will display a subwindow for that module. The contents of the 
                window are similar to that of the main window, except that
                the number of calls (totals or per interval) for each SWI 
                that the module provides are displayed.  The first entry is
                the total for that module, as is displayed in the main window.
                
                Each of the windows for the two Utility module sections have
                256 entries, other modules have up to 64, but only SWI's
                which the module provides names for are displayed. The names 
                in the subwindows are the names of the SWI's that the module 
                provides with module name prefix removed so that more of the 
                name can be displayed.  

Counter Windows Clicking on the All SWI's entry in the main window or any
                entry in a subwindow will call up a counter window, (it
                resembles the X windows program xload).
                
                The counter window shows the number of SWI's (for an
                individual SWI or all SWI's in a module) occurring in the set
                interval, as a vertical line. The display scrolls to the left
                each interval to show a new value, thus the variation in
                activity of a SWI or module can be monitored over a period of
                time.
                
                It is easier to see sudden peaks of activity in a counter
                window than in the main and subwindows, which do not need to
                be open once a counter window has been called up. Any number
                of counter windows (memory permitting) can be active at once.
                
                The counter window display automatically scales up and down
                to fit the maximum value in the window. At the default scale
                4 OS units (1 rectangular pixel) is equivalent to one call, 
                each subsequent scale is half the last shown by the
                horizontal grey lines. These do not represent values but
                show how many times the height of the bars have been halved;
                e.g. 1 line =  scale, 2 lines =  scale, 10 lines 1/1024th
                scale.


Window menu 
-----------
The main window and all subwindows provide a menu, the entries are 
described below.

Totals          This affects the main window and all subwindows. When ticked
                the display of each window gives the total number of calls to
                each SWI or module since the program was first installed. The
                dark grey backed heading of each window will change to show;
                Total SWI calls since initialisation.
                
Per interval    This also affects the main window and all subwindows; it 
                changes the displays to show the number of SWI calls in a 
                given time interval, set by Update rate below. The headings 
                change to SWI calls per rate (actual rate) ms. Where rate is 
                the set rate and actual rate is the rate achieved, see below.
                
Update rate     The value entered into the writable sub menu determines the 
                interval used when displaying in Per interval mode, and the 
                update rate of counter windows, which always show the number 
                of SWI's in this interval in both Totals and Per interval 
                modes.
                
                The value entered is in milliseconds (1/1000th sec), due to 
                RISC OS limitations it is only possible to set the rate to 
                the nearest 10ms, a minimum of 100ms is imposed. When using 
                large values it should be noted that the new value only 
                comes into effect on the next scheduled update.
                
                If a lot of tasks are running or a number of subwindows or 
                counter windows are open it may not be possible for the 
                program to update its displays at very high rates, this is 
                automatically taken into account, and the values and sizes of 
                bars are corrected accordingly.

Scale           Bars in the main and subwindows are automatically scaled to 
                fit the largest in the window by default, this can however, 
                lead to the bars for small values disappearing. Clicking on 
                the Scale option on the main menu toggles automatic and 
                manual scaling, which is shown by a tick next to scale.

                When using manual scaling values can be entered in the 
                writable submenu, the top entry multiplies the size of the 
                bar, and the bottom entry divides it. Some multipliers are 
                not allowed when values becomes very large, to prevent 
                integer overflow.
                
Tasks           !SWIstat monitors the SWI activity of all active RISC OS 
                tasks as default. By using the task menu, the activity of a 
                particular task can be monitored in isolation, by choosing 
                its name from the task list. This makes it easier to 
                scrutinise the calls made by a task which is currently under
                test.
                
                As !SWIstat must make a number of SWI calls itself in order 
                to update the displays, the activity of all tasks Except 
                !SWIstat can be shown using this option. The All Tasks entry 
                will restore the default behaviour.

Zero Counts     This option will zero the counts for all SWIs which can be
                seen when displaying totals. All counter windows are also 
                cleared. This option can be used after changing the task 
                being monitored using the Tasks menu described above. 
                This will clear the totals so that only calls from the 
                particular task are displayed subsequently.


Iconbar menu
------------
Info            Displays program information and version number.

Display         Displays the main window, equivalent to clicking on the
                !SWIstat icon.
                
Reinit          If you or an application install more SWI providing modules 
                after the !SWIstat application has started, they will not be 
                recognised unless the ReInit option is used. This resets the 
                totals since initialisation to zero, closes all subwindows 
                and counter windows, and re-displays the main window with 
                the new modules.
                
Kill            Quits the application and kills the SWImod module which 
                performs the counting of SWIs. This ensures the small 
                processing overhead imposed by the module is removed.

Quit            Quits the application, the SWImod module is not killed so 
                if the program is run again, the SWI totals will still have 
                been incremented while the program was not running, see 
                Technical details below.



Technical details
=================

!SWIstat works by installing a special module SWImod which claims the SWI 
vector. The details below are provided for users who may wish to use this 
module in their own programs.

On initialisation the SWImod module interrogates each module in turn to 
determine whether it provides SWI's, if it does a piece of RMA workspace is 
claimed to store the total number of calls to each SWI. It then claims the
SWI  vector and increments the correct value every time a SWI is called. The
SWImod module is controlled using the following SWIs.

SWI_stat (&49080)       !SWIstat uses this call every update interval to read
                        the current SWI use counts, and calculate the correct
                        values for the program displays.
                        
                        A call to SWI_stat (no parameters required) returns a
                        pointer in R0 to a memory structure (type: main_str)
                        which is described in C as:

    typedef struct
    {
        struct mod__str *chain_ptr;       /* pointer to chain of mod_str    */
        int              swi_total;       /* total of all SWIs called      */
        int              totals[2];       /* total of 1st & 2nd 256 SWIs   */
        int              counts[512];     /* usage counts for 1st 512 SWIs */
    } main_str;

    typedef struct mod__str
    {
        struct mod__str *next_ptr;        /* pointer to next in chain       */
        int              chunk_no;        /* chunk number of module         */
        int              mod_total;       /* total of all SWIs by module   */
        char             mod_name[24];    /* name of module                 */
        int              counts[64];      /* usage counts for 64 mod SWIs  */
    } mod_str;


SWI_Zero (&49081)       Calling this routine causes all the SWI counts to be
                        zeroed. Counting continues immediately.

SWI_Control (&49082)    This call is used to activate (R0 = 1) or suspend
                        (R0 = 0) the modules counting activity. While
                        suspended the SWI vector is still claimed, but
                        computational overhead of the counting operation
                        is removed.

SWI_Filter (&49083)     This call controls which tasks are monitored by 
                        SWImod. The value of R0 are R1 control the operation.
                        
                        R0 = 0  All tasks are monitored (default).
                        R0 = 1  R1 = task handle to exclusively monitor.
                        R0 = 2  R1 = task handle to exclude,
                                i.e. monitor all except R1.
                                
                        The monitoring of tasks is performed using a WIMP
                        postfilter mechanism, to enable or disable the
                        counting of SWIs depending on the task the WIMP
                        has just switched in. Calls made by the operating 
                        system during a WIMP_Poll are assigned to the task 
                        which called it.



!APPstat
========

Also from DEEJ Technology PLC is the companion application !APPstat.  Using
the same style of displays !APPstat provides microsecond accurate  timing
information on the amount of processing performed by each  application.

It is the best tool currently available to help programmers to see the
results of  optimising various parts of their programs, and to decide how
much time  should be spent in Idle processing, without being antisocial to
other  applications.

It also provides information and timings on the event types and message
action  types from Wimp_Poll's which are currently being delivered to
different  tasks, so the parts of a program taking up execution time can be
identified.



End of SWIstat User Guide.
