

                        Module Service Call Statistics
                        ==============================

                        
Documentation for !SERVstat application version 1.20 (10-Apr-2021)
for RISC OS 3.1 and later.

Issue: 1.20 (10-Apr-2021), replaces: 0.10 (22-Jun-1998)
                                     1.00 (18-Aug-2001)
                                     1.01 (17-Nov-2002)
                                     1.11 (11-Apr-2020)

Author: David J Ruck

Copyright  DEEJ Technology PLC 2021 


Overview
========

The !SERVstat application provides information on the activity of all module 
service calls occurring in your machine. It is intended for programmers who
wish to debug a module's service call interface with the OS. It does this by
showing exactly which calls are being made, when and in what quantity.


Using !SERVstat
===============

When started !SERVstat installs its own icon on the icon bar, clicking on it 
will display the main window. This window contains information on groups of 
service calls.

Most service calls have a numeric value below 256 are located in the system 
group. Other service calls have values based on their module SWI chunk 
number, these are sorted into groups with a name based on the prefix of the 
SWIs. If the prefix is not available the hexadecimal chunk number will be 
used instead.

Each group 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 service 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 !SERVstat menu section below.

The Main Window The first entry in the window is the total value of all the
                entries below. The system group contains the first 256 service
                calls and the other groups have 64  calls from the SWI chunk
                base onwards.

Sub Windows     Clicking on any of the module names (not the All Service 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
                service call are displayed. The first entry is the total for
                that module, as is displayed in the main window.
                
                Most documented service calls are displayed using their
                offical names. Those  not known by the program displayed as
                service <n>.

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

                The counter window shows the number of service 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 Service
                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 Service 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           !SERVstat monitors the service 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 SERVstat can be used to filter out any
                service calls issued while !SERVstat is active. The All
                Tasks entry will restore the default behaviour.

Zero Counts     This option will zero the counts for all service 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
                !SERVstat 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 SERVmod module which
                performs the  counting of service calls. This ensures the
                small processing overhead imposed  by the module is removed.

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



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

On initialisation the SERVmod module claims some workspace to store counts 
of the first 256 (system) service calls, and then wait for service calls to
be  issued in the normal manor. On receiving a service 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 service call table format, but requests all 
service calls be given to it.

The SERVmod module is controlled using the following SWIs. 

SERV_stat                !SERVstat uses this call every update interval to 
&55940                   read the current call 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       serv_total;        /* total of all service call      */
            int       sys_total;         /* total of 1st 256 services      */
            int       counts[256];       /* usage counts for 1st 256 calls */
        } 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 services by module*/
            int       counts[64];        /* usage counts for 64 mod calls  */
        } mod_str;

                         The list structure can grow dynamically when a new
                         service call range is encountered.

SERV_Zero                Calling this routine causes all the service call
&55941                   counts to be zeroed. Counting  continues immediately.

SERV_Control             This call is used to activate (R0 = 1) or suspend
&55942                   (R0 = 0) the modules counting  activity. While
                         suspended the module still handles alls service
                         calls, but computational overhead of the counting
                         operation is removed.


SERV_Filter              This call controls which tasks are monitored by
&55943                   SERVmod. 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 service 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 SERVstat User Guide.
