1 02/20/85  metering_util_
  2 
  3 
  4 Entry points in metering_util_:
  5    (List is generated by the help command)
  6 
  7 
  8 The metering_util_ subroutine contains several entry points useful for
  9 collecting hardcore metering data.  In general, hardcore metering data
 10 elements can be categorized as samples, cumulative times, or cumulative
 11 counts (the latter two being cumulative since system initialization).
 12 Samples are snapshots of variables that describe the state of some
 13 system object (e.g, number of processes eligible at this instant).  An
 14 example of a cumulative count is the total number of read I/Os issued
 15 to a particular disk device since system initialization, while an
 16 example of a cumulative time is the total busy time of a particular
 17 disk device while processing read I/Os.  It is easy to compute average
 18 I/O time for a read to a particular device from these last two items.
 19 
 20 
 21 If a given set of metering data is sampled periodically, then more
 22 interesting, time-varying data can be computed.  For example, the
 23 average I/O time for a read during a certain time interval can be
 24 computed.  That interval is the time between any two samples of the
 25 data; subtracting the earlier cumulative count of I/Os from the later
 26 count yields the incremental count (i.e., the count of I/Os during the
 27 interval).
 28 
 29 
 30 Multics metering commands are designed for interactive use, with the
 31 interval boundaries defined by the user in real time.  Typically,
 32 metering commands support the following control arguments:
 33 -report
 34    prints a report of activity since the last interval boundary (or
 35    since system initialization, if no boundary has been defined).
 36 -reset
 37    defines an interval boundary for this metering program; all further
 38    invocations of this command display data reflecting activity since
 39    this boundary.
 40 -report_reset
 41    reports and then resets.
 42 
 43 
 44 Under this scheme, each display of data, establishment of an interval
 45 boundary, etc., is done in a separate invocation of the same metering
 46 program.  This allows the user to establish an interval boundary,
 47 exercise the system in some fashion, and then print data describing the
 48 system performance while it was being exercised.  Additionally, a user
 49 can run any number of metering programs, each with independent interval
 50 boundaries.  These considerations imply that metering data collection
 51 (which is sampling of hardcore data bases) should be global to the
 52 process (in order to exist through multiple invocations of the same
 53 metering command) and be distinguished among different metering
 54 programs.
 55 
 56 
 57 To use this subroutine, sufficient access to copy all hardcore regions
 58 specified is required.  Access to the phcs_ gate is sufficient.  If all
 59 hardcore regions specified are defined in
 60 >sl1>ring_zero_meters_limits.ascii, then access to metering_gate_ is
 61 sufficient.
 62 
 63 
 64 :Entry:  define_regions:  02/20/85 metering_util_$define_regions
 65 
 66 
 67 Function:  This entry is used to define a set of sections of hardcore
 68 data bases which are of interest to the invoker.  Upon return,
 69 sufficient static storage has been allocated to contain two copies of
 70 each hardcore region specified in the call; this storage has also been
 71 initialized to zero.
 72 
 73 
 74 Syntax:
 75 declare code fixed bin (35); declare unique_index fixed bin; declare
 76      metering_util_$define_regions entry options (variable);
 77 call metering_util_$define_regions (unique_index, code,
 78           hardcore_seg_1, begin_region_1, end_region_1, ...  , ...  ,
 79           ...  hardcore_seg_n, begin_region_n, end_region_n);
 80 
 81 
 82 Arguments:
 83 unique_index
 84    is a unique identifier for the set of regions.  This identifier must
 85    be used in calls to other metering_util_ entry points.  (Output)
 86 code
 87    is a standard status code.  The code error_table_$wrong_no_of_args
 88    is returned if the number of arguments remaining is not modulo 3.
 89    (Output)
 90 
 91 
 92 The remaining arguments must be in groups of three, as shown in the
 93 calling sequence above.  Each such group defines a hardcore region by
 94 specifying a hardcore segment and a contiguous region within the
 95 segment.  The arguments in each group, in order, are the following:
 96 hardcore_seg_i
 97    identifies the ring 0 data base.  It may be of the form char (*), in
 98    which case it is assumed to be the name of a ring 0 segment; or of
 99    the form ptr aligned, in which case it is assumed to be a pointer to
100    the segment.  In the latter case, only the segment number is
101    significant.  (Input)
102 
103 
104 begin_region_i
105    identifies the beginning of the region in the ring 0 data base.  It
106    may be of the form char (*), in which case it is assumed to be the
107    name of an external symbol in hardcore_seg_i; or of the form fixed
108    bin, in which case it is assumed to be a word offset into
109    hardcore_seg_i.  (Input)
110 end_region_i
111    identifies the end of the region in the ring 0 data base.  It may be
112    of the form char (*), in which case it is assumed to be the name of
113    an external symbol in hardcore_seg_i that refers to the next word
114    beyond the end of the region; or of the form fixed bin, in which
115    case it is assumed to be the length of the region in words.  (Input)
116 
117 
118 Notes:  Any errors encountered by this entry point are reported to the
119 user by means of the sub_err_ subroutine.  Examples of such errors are
120 invalid segment names or symbol names, or invalid region specification
121 (e.g., nonpositive length).  Errors of this sort are always programming
122 errors, and are not external circumstances from which the calling
123 program can be expected to recover.
124 
125 
126 :Entry:  fill_buffers:  02/20/85 metering_util_$fill_buffers
127 
128 
129 Function:  This entry is used to copy the current contents of all
130 regions defined for the specified unique identifier into the current
131 buffers for that unique identifier, and to return pointers to the
132 current and previous buffers for these regions.
133 
134 
135 Syntax:
136 declare metering_util_$fill_buffers entry (fixed bin, fixed bin(71),
137      char(10), (*) ptr, (*) ptr, fixed bin(35));
138 call metering_util_$fill_buffers (unique_index, meter_time,
139      formatted_time, current_ptrs, previous_ptrs, code);
140 
141 
142 Arguments:
143 unique_index
144    is the unique identifier returned by metering_util_$define_regions
145    (above).  (Input)
146 meter_time
147    is the total metering time in microseconds.  The total metering time
148    is defined as the time between the last call to metering_util_$reset
149    and this call.  If metering_util_$reset has not been called, the
150    total metering time is defined as the time between the last system
151    bootload and this call.  (Output)
152 
153 
154 formatted_time
155    is the total metering time in a format suitable for printing.  This
156    format is
157       HHHH:MM:SS
158    where this represents the decomposition of total metering time into
159    hours (HH), minutes (MM), and seconds (SS).  (Output)
160 current_ptrs
161    is an array of pointers that, on return, contain pointers to the
162    current buffers for the hardcore regions defined in the call to
163    metering_util_$define_regions.  The number of elements in this array
164    must be equal to the number of hardcore regions defined in the call
165    to metering_util$define regions.  The elements of this array are
166    pointers to the current buffers for the corresponding hardcore
167    regions.  Specifically, current_ptrs (i) contains on return a
168    pointer to the current buffer for hardcore_seg_i (defined above).
169    (Output)
170 
171 
172 previous_ptrs
173    is an array of pointers which, on return, contain pointers to the
174    previous buffers for the hardcore regions defined in the call to
175    metering_util_$define_regions.  The number of elements in this array
176    must be equal to the number of hardcore regions defined in the call
177    to metering_util_$define regions.  The elements of this array are
178    pointers to the previous buffers for the corresponding hardcore
179    regions.  Specifically, previous_ptrs (i) contains on return a
180    pointer to the previous buffer for hardcore_seg_i (defined above).
181    (Output)
182 code
183    is a standard status code.  If either the array current_ptrs or the
184    array previous_ptrs does not have the proper number of elements (see
185    above), the code error_table_$invalid_array_size is returned, and no
186    action is performed.  (Output)
187 
188 
189 :Entry:  reset:  02/20/85 metering_util_$reset
190 
191 
192 Function:  This entry point is called to reset the metering interval to
193 the time of this call.  This is done by copying the current buffers
194 into the previous buffers for all regions defined for the unique index
195 specified.
196 
197 
198 Syntax:
199 declare metering_util_$reset entry (fixed bin, fixed bin(35));
200 call metering_util_$reset (unique_index, code);
201 
202 
203 Arguments:
204 unique_index
205    is as above.  (Input)
206 code
207    is as above.  (Output)