ARM Club 3

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / programming / servstat / !SERVstat / !Help next >

Wrap

Text File | 1998-06-22 | 11.8 KB | 243 lines

Module Service Call Statistics ============================== Documentation for !SERVstat application version 0.10 20-Jun-1998 for RISC OS 3.1 and later. Issue: 0.10/T 22-Jun-1998, replaces: Author: David J Ruck Copyright © DEEJ Technology PLC 1998 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 SWI’s. 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 it’s 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 SWI’s. Note: The SWI chunk number for APPmod is currently provisional and will change on receiving official Acorn registration. SERV_stat !SERVstat uses this call every update interval to (&C46C0 provisional) 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 (&C46C1 provisional) counts to be zeroed. Counting continues immediately. SERV_Control This call is used to activate (R0 = 1) or suspend (&C46C2 provisional) (R0 = 0) the modules counting activity. While suspended the module still handles alls service calls, but computational overhead of the counting operation is removed. (&C46C3 provisional) SERV_Filter This call controls which tasks are monitored by 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.