00001 /* 00002 * stats.h - statistical package interfaces 00003 * 00004 * This file is a part of the SimpleScalar tool suite written by 00005 * Todd M. Austin as a part of the Multiscalar Research Project. 00006 * 00007 * The tool suite is currently maintained by Doug Burger and Todd M. Austin. 00008 * 00009 * Copyright (C) 1994, 1995, 1996, 1997, 1998 by Todd M. Austin 00010 * 00011 * This source file is distributed "as is" in the hope that it will be 00012 * useful. The tool set comes with no warranty, and no author or 00013 * distributor accepts any responsibility for the conseqauences of its 00014 * use. 00015 * 00016 * Everyone is granted permission to copy, modify and redistribute 00017 * this tool set under the following conditions: 00018 * 00019 * This source code is distributed for non-commercial use only. 00020 * Please contact the maintainer for restrictions applying to 00021 * commercial use. 00022 * 00023 * Permission is granted to anyone to make or distribute copies 00024 * of this source code, either as received or modified, in any 00025 * medium, provided that all copyright notices, permission and 00026 * nonwarranty notices are preserved, and that the distributor 00027 * grants the recipient permission for further redistribution as 00028 * permitted by this document. 00029 * 00030 * Permission is granted to distribute this file in compiled 00031 * or executable form under the same conditions that apply for 00032 * source code, provided that either: 00033 * 00034 * A. it is accompanied by the corresponding machine-readable 00035 * source code, 00036 * B. it is accompanied by a written offer, with no time limit, 00037 * to give anyone a machine-readable copy of the corresponding 00038 * source code in return for reimbursement of the cost of 00039 * distribution. This written offer must permit verbatim 00040 * duplication by anyone, or 00041 * C. it is distributed by someone who received only the 00042 * executable form, and is accompanied by a copy of the 00043 * written offer of source code that they received concurrently. 00044 * 00045 * In other words, you are welcome to use, share and improve this 00046 * source file. You are forbidden to forbid anyone else to use, share 00047 * and improve what you give them. 00048 * 00049 * INTERNET: dburger@cs.wisc.edu 00050 * US Mail: 1210 W. Dayton Street, Madison, WI 53706 00051 * 00052 * $Id: stats.h,v 1.1.1.1 2003/09/18 00:57:54 panalyzer Exp $ 00053 * 00054 * $Log: stats.h,v $ 00055 * Revision 1.1.1.1 2003/09/18 00:57:54 panalyzer 00056 * 00057 * 00058 * Revision 1.1.1.1 2003/09/18 00:18:44 panalyzer 00059 * 00060 * 00061 * Revision 1.1.1.1 2003/09/16 18:48:14 gdm 00062 * 00063 * 00064 * Revision 1.1.1.1 2000/11/29 14:53:54 cu-cs 00065 * Grand unification of arm sources. 00066 * 00067 * 00068 * Revision 1.1.1.1.2.1 2000/10/13 17:44:44 chriswea 00069 * added stuff for ptrace 00070 * 00071 * Revision 1.2 2000/09/08 22:55:06 chriswea 00072 * for some reason these files were not updated before ??? 00073 * 00074 * Revision 1.1.1.1 2000/05/26 15:18:59 taustin 00075 * SimpleScalar Tool Set 00076 * 00077 * 00078 * Revision 1.3 1999/12/31 18:54:02 taustin 00079 * quad_t naming conflicts removed 00080 * 00081 * Revision 1.2 1998/08/27 16:40:23 taustin 00082 * implemented host interface description in host.h 00083 * added target interface support 00084 * added support for MS VC++ compilation 00085 * added support for qword's 00086 * 00087 * Revision 1.1 1997/03/11 01:34:26 taustin 00088 * Initial revision 00089 * 00090 * 00091 */ 00092 00093 #ifndef STAT_H 00094 #define STAT_H 00095 00096 #include <stdio.h> 00097 00098 #include "host.h" 00099 #include "machine.h" 00100 #include "eval.h" 00101 00102 /* 00103 * The stats package is a uniform module for handling statistical variables, 00104 * including counters, distributions, and expressions. The user must first 00105 * create a stats database using stat_new(), then statical counters are added 00106 * to the database using the *_reg_*() functions. Interfaces are included to 00107 * allocate and manipulate distributions (histograms) and general expression 00108 * of other statistical variables constants. Statistical variables can be 00109 * located by name using stat_find_stat(). And, statistics can be print in 00110 * a highly standardized and stylized fashion using stat_print_stats(). 00111 */ 00112 00113 /* stat variable classes */ 00114 enum stat_class_t { 00115 sc_int = 0, /* integer stat */ 00116 sc_uint, /* unsigned integer stat */ 00117 #ifdef HOST_HAS_QWORD 00118 sc_qword, /* qword integer stat */ 00119 sc_sqword, /* signed qword integer stat */ 00120 #endif /* HOST_HAS_QWORD */ 00121 sc_float, /* single-precision FP stat */ 00122 sc_double, /* double-precision FP stat */ 00123 sc_dist, /* array distribution stat */ 00124 sc_sdist, /* sparse array distribution stat */ 00125 sc_formula, /* stat expression formula */ 00126 sc_NUM 00127 }; 00128 00129 /* sparse array distributions are implemented with a hash table */ 00130 #define HTAB_SZ 1024 00131 #define HTAB_HASH(I) ((((I) >> 8) ^ (I)) & (HTAB_SZ - 1)) 00132 00133 /* hash table bucket definition */ 00134 struct bucket_t { 00135 struct bucket_t *next; /* pointer to the next bucket */ 00136 md_addr_t index; /* bucket index - as large as an addr */ 00137 unsigned int count; /* bucket count */ 00138 }; 00139 00140 /* forward declaration */ 00141 struct stat_stat_t; 00142 00143 /* enable distribution components: index, count, probability, cumulative */ 00144 #define PF_COUNT 0x0001 00145 #define PF_PDF 0x0002 00146 #define PF_CDF 0x0004 00147 #define PF_ALL (PF_COUNT|PF_PDF|PF_CDF) 00148 00149 /* user-defined print function, if this option is selected, a function of this 00150 form is called for each bucket in the distribution, in ascending index 00151 order */ 00152 typedef void 00153 (*print_fn_t)(struct stat_stat_t *stat, /* the stat variable being printed */ 00154 md_addr_t index, /* entry index to print */ 00155 int count, /* entry count */ 00156 double sum, /* cumulative sum */ 00157 double total); /* total count for distribution */ 00158 00159 /* statistical variable definition */ 00160 struct stat_stat_t { 00161 struct stat_stat_t *next; /* pointer to next stat in database list */ 00162 char *name; /* stat name */ 00163 char *desc; /* stat description */ 00164 char *format; /* stat output print format */ 00165 enum stat_class_t sc; /* stat class */ 00166 union stat_variant_t { 00167 /* sc == sc_int */ 00168 struct stat_for_int_t { 00169 int *var; /* integer stat variable */ 00170 int init_val; /* initial integer value */ 00171 } for_int; 00172 /* sc == sc_uint */ 00173 struct stat_for_uint_t { 00174 unsigned int *var; /* unsigned integer stat variable */ 00175 unsigned int init_val; /* initial unsigned integer value */ 00176 } for_uint; 00177 #ifdef HOST_HAS_QWORD 00178 /* sc == sc_qword */ 00179 struct stat_for_qword_t { 00180 qword_t *var; /* qword integer stat variable */ 00181 qword_t init_val; /* qword integer value */ 00182 } for_qword; 00183 /* sc == sc_sqword */ 00184 struct stat_for_sqword_t { 00185 sqword_t *var; /* signed qword integer stat variable */ 00186 sqword_t init_val; /* signed qword integer value */ 00187 } for_sqword; 00188 #endif /* HOST_HAS_QWORD */ 00189 /* sc == sc_float */ 00190 struct stat_for_float_t { 00191 float *var; /* float stat variable */ 00192 float init_val; /* initial float value */ 00193 } for_float; 00194 /* sc == sc_double */ 00195 struct stat_for_double_t { 00196 double *var; /* double stat variable */ 00197 double init_val; /* initial double value */ 00198 } for_double; 00199 /* sc == sc_dist */ 00200 struct stat_for_dist_t { 00201 unsigned int init_val; /* initial dist value */ 00202 unsigned int *arr; /* non-sparse array pointer */ 00203 unsigned int arr_sz; /* array size */ 00204 unsigned int bucket_sz; /* array bucket size */ 00205 int pf; /* printables */ 00206 char **imap; /* index -> string map */ 00207 print_fn_t print_fn; /* optional user-specified print fn */ 00208 unsigned int overflows; /* total overflows in stat_add_samples() */ 00209 } for_dist; 00210 /* sc == sc_sdist */ 00211 struct stat_for_sdist_t { 00212 unsigned int init_val; /* initial dist value */ 00213 struct bucket_t **sarr; /* sparse array pointer */ 00214 int pf; /* printables */ 00215 print_fn_t print_fn; /* optional user-specified print fn */ 00216 } for_sdist; 00217 /* sc == sc_formula */ 00218 struct stat_for_formula_t { 00219 char *formula; /* stat formula, see eval.h for format */ 00220 } for_formula; 00221 } variant; 00222 }; 00223 00224 /* statistical database */ 00225 struct stat_sdb_t { 00226 struct stat_stat_t *stats; /* list of stats in database */ 00227 struct eval_state_t *evaluator; /* an expression evaluator */ 00228 }; 00229 00230 /* evaluate a stat as an expression */ 00231 struct eval_value_t 00232 stat_eval_ident(struct eval_state_t *es);/* expression stat to evaluate */ 00233 00234 /* create a new stats database */ 00235 struct stat_sdb_t *stat_new(void); 00236 00237 /* delete a stats database */ 00238 void 00239 stat_delete(struct stat_sdb_t *sdb); /* stats database */ 00240 00241 /* register an integer statistical variable */ 00242 struct stat_stat_t * 00243 stat_reg_int(struct stat_sdb_t *sdb, /* stat database */ 00244 char *name, /* stat variable name */ 00245 char *desc, /* stat variable description */ 00246 int *var, /* stat variable */ 00247 int init_val, /* stat variable initial value */ 00248 char *format); /* optional variable output format */ 00249 00250 /* register an unsigned integer statistical variable */ 00251 struct stat_stat_t * 00252 stat_reg_uint(struct stat_sdb_t *sdb, /* stat database */ 00253 char *name, /* stat variable name */ 00254 char *desc, /* stat variable description */ 00255 unsigned int *var, /* stat variable */ 00256 unsigned int init_val, /* stat variable initial value */ 00257 char *format); /* optional variable output format */ 00258 00259 #ifdef HOST_HAS_QWORD 00260 /* register a qword integer statistical variable */ 00261 struct stat_stat_t * 00262 stat_reg_qword(struct stat_sdb_t *sdb, /* stat database */ 00263 char *name, /* stat variable name */ 00264 char *desc, /* stat variable description */ 00265 qword_t *var, /* stat variable */ 00266 qword_t init_val, /* stat variable initial value */ 00267 char *format); /* optional variable output format */ 00268 00269 /* register a signed qword integer statistical variable */ 00270 struct stat_stat_t * 00271 stat_reg_sqword(struct stat_sdb_t *sdb, /* stat database */ 00272 char *name, /* stat variable name */ 00273 char *desc, /* stat variable description */ 00274 sqword_t *var, /* stat variable */ 00275 sqword_t init_val, /* stat variable initial value */ 00276 char *format); /* optional variable output format */ 00277 #endif /* HOST_HAS_QWORD */ 00278 00279 /* register a float statistical variable */ 00280 struct stat_stat_t * 00281 stat_reg_float(struct stat_sdb_t *sdb, /* stat database */ 00282 char *name, /* stat variable name */ 00283 char *desc, /* stat variable description */ 00284 float *var, /* stat variable */ 00285 float init_val, /* stat variable initial value */ 00286 char *format); /* optional variable output format */ 00287 00288 /* register a double statistical variable */ 00289 struct stat_stat_t * 00290 stat_reg_double(struct stat_sdb_t *sdb, /* stat database */ 00291 char *name, /* stat variable name */ 00292 char *desc, /* stat variable description */ 00293 double *var, /* stat variable */ 00294 double init_val, /* stat variable initial value */ 00295 char *format); /* optional variable output format */ 00296 00297 /* create an array distribution (w/ fixed size buckets) in stat database SDB, 00298 the array distribution has ARR_SZ buckets with BUCKET_SZ indicies in each 00299 bucked, PF specifies the distribution components to print for optional 00300 format FORMAT; the indicies may be optionally replaced with the strings 00301 from IMAP, or the entire distribution can be printed with the optional 00302 user-specified print function PRINT_FN */ 00303 struct stat_stat_t * 00304 stat_reg_dist(struct stat_sdb_t *sdb, /* stat database */ 00305 char *name, /* stat variable name */ 00306 char *desc, /* stat variable description */ 00307 unsigned int init_val, /* dist initial value */ 00308 unsigned int arr_sz, /* array size */ 00309 unsigned int bucket_sz, /* array bucket size */ 00310 int pf, /* print format, use PF_* defs */ 00311 char *format, /* optional variable output format */ 00312 char **imap, /* optional index -> string map */ 00313 print_fn_t print_fn); /* optional user print function */ 00314 00315 /* create a sparse array distribution in stat database SDB, while the sparse 00316 array consumes more memory per bucket than an array distribution, it can 00317 efficiently map any number of indicies from 0 to 2^32-1, PF specifies the 00318 distribution components to print for optional format FORMAT; the indicies 00319 may be optionally replaced with the strings from IMAP, or the entire 00320 distribution can be printed with the optional user-specified print function 00321 PRINT_FN */ 00322 struct stat_stat_t * 00323 stat_reg_sdist(struct stat_sdb_t *sdb, /* stat database */ 00324 char *name, /* stat variable name */ 00325 char *desc, /* stat variable description */ 00326 unsigned int init_val, /* dist initial value */ 00327 int pf, /* print format, use PF_* defs */ 00328 char *format, /* optional variable output format */ 00329 print_fn_t print_fn); /* optional user print function */ 00330 00331 /* add NSAMPLES to array or sparse array distribution STAT */ 00332 void 00333 stat_add_samples(struct stat_stat_t *stat,/* stat database */ 00334 md_addr_t index, /* distribution index of samples */ 00335 int nsamples); /* number of samples to add to dist */ 00336 00337 /* add a single sample to array or sparse array distribution STAT */ 00338 void 00339 stat_add_sample(struct stat_stat_t *stat,/* stat variable */ 00340 md_addr_t index); /* index of sample */ 00341 00342 /* register a double statistical formula, the formula is evaluated when the 00343 statistic is printed, the formula expression may reference any registered 00344 statistical variable and, in addition, the standard operators '(', ')', '+', 00345 '-', '*', and '/', and literal (i.e., C-format decimal, hexidecimal, and 00346 octal) constants are also supported; NOTE: all terms are immediately 00347 converted to double values and the result is a double value, see eval.h 00348 for more information on formulas */ 00349 struct stat_stat_t * 00350 stat_reg_formula(struct stat_sdb_t *sdb,/* stat database */ 00351 char *name, /* stat variable name */ 00352 char *desc, /* stat variable description */ 00353 char *formula, /* formula expression */ 00354 char *format); /* optional variable output format */ 00355 00356 /* print the value of stat variable STAT */ 00357 void 00358 stat_print_stat(struct stat_sdb_t *sdb, /* stat database */ 00359 struct stat_stat_t *stat,/* stat variable */ 00360 FILE *fd); /* output stream */ 00361 00362 /* print the value of all stat variables in stat database SDB */ 00363 void 00364 stat_print_stats(struct stat_sdb_t *sdb,/* stat database */ 00365 FILE *fd); /* output stream */ 00366 00367 00368 /* find a stat variable, returns NULL if it is not found */ 00369 struct stat_stat_t * 00370 stat_find_stat(struct stat_sdb_t *sdb, /* stat database */ 00371 char *stat_name); /* stat name */ 00372 00373 00374 /* print a sparse array distribution */ 00375 void 00376 print_sdist(struct stat_stat_t *stat, /* stat variable */ 00377 FILE *fd); /* output stream */ 00378 00379 /* print an array distribution */ 00380 void 00381 print_dist(struct stat_stat_t *stat, /* stat variable */ 00382 FILE *fd); /* output stream */ 00383 00384 #endif /* STAT_H */