1 02/25/85  meter_gate, mg
 2 
 3 Syntax as a command:  mg STR {entry_nm} {-control_arg}
 4 
 5 
 6 Function:  is used to interpret and print per-system metering
 7 information for entries in specified hardcore gates.
 8 
 9 
10 Arguments:
11 STR
12    is the name of the gate segment to be examined; i.e., hcs_, phcs_,
13    hphcs_, ioi_, hc_backup_, etc.
14 entry_nm
15    is the name of a single entry in the specified gate.  Only the
16    information for that entry is printed.  If entry_nm is not
17    specified, information for all entries is printed.  No control
18    argument can be given if an entry_nm is specified.
19 
20 
21 Control arguments:
22 -average, -av
23    sorts the output on the average time spent in each entry.
24 -call, -cl
25    sorts the output on total calls to each entry.
26 -page, -pg
27    sorts the output on the average number of page faults in each entry.
28 -reset, -rs
29    resets the metering interval for the invoking process so that the
30    interval begins at the last call with -reset specified.  If -reset
31    has never been given in a process, it is equivalent to having been
32    specified at system initialization time.
33 -time, -tm
34    sorts the output on the total time spent in each entry.
35 
36 
37 Notes:  If the meter_gate command is given with no control argument, it
38 does not sort the output.
39 
40 The output header consists of the time the system was brought up, the
41 current time, and the total charge time (which equals total_cpu_time
42 minus idle_time).  Also printed is the total number of calls to the
43 gate, the amount of time spent in the entries that were called, and the
44 percentage of total charged time that was spent in the entries that
45 were called.
46 
47 
48 Metering information is collected only for gate segments defined with
49 the "hgate" macro, and only for those entries in the segment defined
50 with the "gate" macro (refer to the gate_macros.incl.alm include file
51 for these macros, and refer to the source listing of a particular gate
52 to apply this principle).  For example, some hardcore gate entries are
53 defined with the "fgate" macro for efficiency or because ring 0 stack
54 history is abandoned during the call (e.g., hcs_$block); such gate
55 entries are not metered.
56 
57 The following is a brief description of the variables printed out by
58 the meter_gate command.
59 calls
60    is the total number of times the gate entry point was called.
61 
62 
63 pcnt
64    is the percentage of total charge time spent in the called segment.
65 avg
66    is the average virtual time in milliseconds spent in the called
67    segment.
68 pfault
69    is the average number of page faults incurred during a call to a
70    segment through the specified entry.
71 entry name
72    is the name of an entry point to the gate.