

                        Vector Call Statistics
                        ======================

                        
Documentation for VecStat application version 1.20 (10-Apr-2021)
for RISC OS 3.5 and later.

Issue: 1.20 (10-Apr-2021), replaces: 0.10 (20-Feb-2000)
                                     1.00 (18-Aug-2001)
                                     1.01 (17-Nov-2002)
                                     1.02 (04-Jan-2003)
                                     1.03 (31-Jul-2004)
                                     1.10 (11-Apr-2020)
Author: David J Ruck

Copyright  DEEJ Technology PLC 2020


Overview
========

The VecStat application provides information on the activity of all software
vectors occurring in your machine. It is intended as an debugging aid for
programmers  enabling the monitoring of the use of various OS interfaces. It
does this by showing exactly which calls are being made, when and in what
quantity.


Using VecStat
===============

When started VecStat installs its own icon on the icon bar, clicking on it 
will display the main window. This window contains information on each
Vector.

Each vector entry displays 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 calls made on the vector 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 VecStat menu
section below.

The Main Window The first entry in the window is the total value of all the
                entries below. 

Sub Windows     Clicking on any of the module names (not the All Vector Calls
                entry) will display a subwindow for that group. 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
                reason codes are displayed. The first entry is the total for
                that module, as is displayed in the main window.
                
                Most documented reason codes are displayed using their
                offical names. Those not known by the program displayed as
                as a numeric value.
                
                The following vectors have reason codes
                            
                WRITECV     R0   Charater code
                ByteV       R0   OS_Byte reason code
                WordV       R0   OS_Word reason code
                FileV       R0   OS_File reason code
                ArgsV       R0   OS_Args reason code
                GBPBV       R0   OS_GBPB reason code
                FindV       R0   OS_Find reason code
                FSControlV  R0   OS_FSContol reason code
                EventV      R0   event number
                INSV        R1   buffer number
                REMV        R1   buffer number
                CNPV        R1   buffer number
                UKVDU23     R0   byte option
                UKSWIV      R11  SWI number
                UKPLOTV     R0   plot number
                VDUXV       R0   vdu code
                UpCallV     R0   upcall reason
                ChangeEnvV  R0   handler number
                SpriteV     R0   SpriteOp reason code
                DrawV       R8   SWI base index
                EconetV     R0   reason code
                ColourV     R8   SWI base index
                PaleteV     R4   reason code
                SerialV     R0   OS_SerialOp reason code
                

Counter Windows Clicking on the All Vector Calls entry in the main window or
                any entry in a subwindow will call up a counter window,
                similar to the one for Keyboard Scan files shown opposite, (it
                also resembles the X windows program xload).

                The counter window shows the number of vetcor calls (for an
                individual call or all calls in a group) 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 call or group 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
                since the program was first started. The dark grey backed
                heading of each window will change to show; Total Vector
                calls.

Per interval    This also affects the main window and all subwindows; it
                changes the displays to show the number of calls in a given
                time interval, set by Update rate below. The headings change
                to Vector 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. The example shows
                1/256th scaling. Some multipliers are not allowed when values
                becomes very large, to prevent integer overflow.

Tasks           VecStat monitors the vector call 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.
                
                The option Except VECstat can be used to filter out any
                vector calls issued while VecStat is active. The All
                Tasks entry will restore the default behaviour.

Zero Counts     This option will zero the counts for all vector calls, 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
                VecStat icon.

Reinit          This resets the totals since initialisation to zero, closes
                all subwindows and counter windows, and re-displays the main
                window.

Kill            Quits the application and kills the VECmod module which
                performs the  counting of vector calls. This ensures the
                small processing overhead imposed  by the module is removed.

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



Technical details
=================
VecStat works by installing a special module VECmod. The details below are
provided for users who may wish to use this module in their own programs.

On initialisation the VECmod module claims some workspace to store counts 
of the first 256 (system) vector calls, and then wait for vector calls to
be issued in the normal manor. On receiving a vector call >256 a new piece
of workspace is claimed to count 64 calls in the approprite SWI chunk range.
The module conforms with the new vector call table format, but requests all 
vector calls be given to it.

The VECmod module is controlled using the following SWIs. Note: The  SWI
chunk number for APPmod is currently provisional and will change on 
receiving official Acorn registration.

VEC_stat                 VecStat uses this call every update interval to 
(&55980)                 read the current call counts, and calculate the
                         correct values for the program displays.

                         A call to VEC_stat (no parameters required) returns
                         a pointer in R0 to a  memory structure (type:
                         main_str) which is described in C as:

        typedef struct
        {
            uint             vec_total0;    /* total of all vector calls  */
            uint             vec_total1;    /* high 32 bits               */
            struct
            {
                uint     count;            /* calls to this vector       */
                vec_str *reasons;          /* point to reason structure  */
            } vector[NUM_VECTORS];
        } main_str;
        
        typedef struct
        {
            struct
            {
                 int      code;            /* vector reason code             */
                 uint     count;           /* count per reason code          */
            } reason[NUM_REASONS];
        } vec_str;

                         As there are only 256 reason codes slots for each
                         vector, and some may have more possible values, they
                         are allocated with the following algorith.
                         
                         If <reason> is < 256 and the corresponding slot
                         is empty use that slot, otherwise use the last
                         free slot available. If no free slots ignore
                         (but will still be counted in the totals)
                         
                         This is designed so that low numbered reasons are
                         usualyy at the start of the array and higher numbers
                         added to the end dont steal the lower ones slots.


VEC_Zero                 Calling this routine causes all the vector call
(&55981)                 counts to be zeroed. The reason codes are not
                         reset by this call. Counting continues immediately.


VEC_Control              This call is used to activate (R0 = 1) or suspend
(&55982)                 (R0 = 0) the modules counting  activity. While
                         suspended the module still intercepts all vector
                         calls, but computational overhead of the counting
                         operation is removed.


VEC_Filter               This call controls which tasks are monitored by
(&55983)                 VECmod. The value of R0 and 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
                         post- filter mechanism, to  enable or disable the
                         counting of vector calls 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.

End of VECstat User Guide.
