• Main Page
  • Related Pages
  • Modules
  • Data Structures
  • Files
  • File List
  • Globals

sst/core/techModels/libsim-panalyzer/stats.h

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 */

Generated on Fri Oct 22 2010 11:02:21 for SST by  doxygen 1.7.1