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

sst/elements/genericProc/ssBackEnd/ssb_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: ssb_stats.h,v 1.1.1.1 2006-01-31 16:35:51 afrodri Exp $
00053  *
00054  * $Log: not supported by cvs2svn $
00055  * Revision 1.3  2005/08/16 21:12:55  arodrig6
00056  * changes for docs
00057  *
00058  * Revision 1.2  2004/11/16 04:17:46  arodrig6
00059  * added more documentation
00060  *
00061  * Revision 1.1  2004/08/05 23:51:45  arodrig6
00062  * grabed files from SS and broke up some of them
00063  *
00064  * Revision 1.2  2000/04/10 23:46:42  karu
00065  * converted all quad to qword. NO OTHER change made.
00066  * the tag specfp95-before-quad-qword is a snapshow before this change was made
00067  *
00068  * Revision 1.1.1.1  2000/03/07 05:15:18  karu
00069  * this is the repository created for my own maintanence.
00070  * created when spec95 (lisp and compress worked).
00071  * compress still had the scanf("%i") problem
00072  * DIFF from the repository I am using alongwith ramdass on /projects
00073  * need to merge the two sometime :-)
00074  *
00075  * Revision 1.1.1.1  2000/02/25 21:02:52  karu
00076  * creating cvs repository for ss3-ppc
00077  *
00078  * Revision 1.2  1998/08/27 16:40:23  taustin
00079  * implemented host interface description in host.h
00080  * added target interface support
00081  * added support for MS VC++ compilation
00082  * added support for quadword's
00083  *
00084  * Revision 1.1  1997/03/11  01:34:26  taustin
00085  * Initial revision
00086  *
00087  *
00088  */
00089 
00090 #ifndef STAT_H
00091 #define STAT_H
00092 
00093 #include <stdio.h>
00094 
00095 #include "ssb_host.h"
00096 #include "ssb_machine.h"
00097 //#include "eval.h"
00098 
00099 /*
00100  * The stats package is a uniform module for handling statistical variables,
00101  * including counters, distributions, and expressions.  The user must first
00102  * create a stats database using stat_new(), then statical counters are added
00103  * to the database using the *_reg_*() functions.  Interfaces are included to
00104  * allocate and manipulate distributions (histograms) and general expression
00105  * of other statistical variables constants.  Statistical variables can be
00106  * located by name using stat_find_stat().  And, statistics can be print in
00107  * a highly standardized and stylized fashion using stat_print_stats().
00108  */
00109 
00110 /* stat variable classes */
00111 enum stat_class_t {
00112   sc_int = 0,                   /* integer stat */
00113   sc_uint,                      /* unsigned integer stat */
00114 #ifdef HOST_HAS_QWORD
00115   sc_quad,                      /* quadword integer stat */
00116   sc_squad,                     /* signed quadword integer stat */
00117 #endif /* HOST_HAS_QWORD */
00118   sc_float,                     /* single-precision FP stat */
00119   sc_double,                    /* double-precision FP stat */
00120   sc_dist,                      /* array distribution stat */
00121   sc_sdist,                     /* sparse array distribution stat */
00122   sc_formula,                   /* stat expression formula */
00123   sc_NUM
00124 };
00125 
00126 /* sparse array distributions are implemented with a hash table */
00127 #define HTAB_SZ                 1024
00128 #define HTAB_HASH(I)            ((((I) >> 8) ^ (I)) & (HTAB_SZ - 1))
00129 
00130 //: hash table bucket definition 
00131 //!SEC:ssBack
00132 struct bucket_t {
00133   bucket_t *next;       /* pointer to the next bucket */
00134   md_addr_t index;              /* bucket index - as large as an addr */
00135   unsigned int count;           /* bucket count */
00136 };
00137 
00138 /* forward declaration */
00139 struct stat_stat_t;
00140 
00141 /* enable distribution components:  index, count, probability, cumulative */
00142 #define PF_COUNT                0x0001
00143 #define PF_PDF                  0x0002
00144 #define PF_CDF                  0x0004
00145 #define PF_ALL                  (PF_COUNT|PF_PDF|PF_CDF)
00146 
00147 /* user-defined print function, if this option is selected, a function of this
00148    form is called for each bucket in the distribution, in ascending index
00149    order */
00150 typedef void
00151 (*print_fn_t)( stat_stat_t *stat,       /* the stat variable being printed */
00152               md_addr_t index,          /* entry index to print */
00153               int count,                /* entry count */
00154               double sum,               /* cumulative sum */
00155               double total);            /* total count for distribution */
00156 
00157 //: statistical variable definition 
00158 //!SEC:ssBack
00159 struct stat_stat_t {
00160    stat_stat_t *next;   /* pointer to next stat in database list */
00161   char *name;                   /* stat name */
00162   char *desc;                   /* stat description */
00163   char *format;                 /* stat output print format */
00164   enum stat_class_t sc;         /* stat class */
00165   union stat_variant_t {
00166     /* sc == sc_int */
00167     struct stat_for_int_t {
00168       int *var;                 /* integer stat variable */
00169       int init_val;             /* initial integer value */
00170     } for_int;
00171     /* sc == sc_uint */
00172     struct stat_for_uint_t {
00173       unsigned int *var;        /* unsigned integer stat variable */
00174       unsigned int init_val;    /* initial unsigned integer value */
00175     } for_uint;
00176 #ifdef HOST_HAS_QWORD
00177     /* sc == sc_quad */
00178     struct stat_for_qword_t {
00179       qword_t *var;             /* quadword integer stat variable */
00180       qword_t init_val;         /* quadword integer value */
00181     } for_quad;
00182     /* sc == sc_squad */
00183     struct stat_for_sqword_t {
00184       sqword_t *var;            /* signed quadword integer stat variable */
00185       sqword_t init_val;                /* signed quadword integer value */
00186     } for_squad;
00187 #endif /* HOST_HAS_QWORD */
00188     /* sc == sc_float */
00189     struct stat_for_float_t {
00190       float *var;               /* float stat variable */
00191       float init_val;           /* initial float value */
00192     } for_float;
00193     /* sc == sc_double */
00194     struct stat_for_double_t {
00195       double *var;              /* double stat variable */
00196       double init_val;          /* initial double value */
00197     } for_double;
00198     /* sc == sc_dist */
00199     struct stat_for_dist_t {
00200       unsigned int init_val;    /* initial dist value */
00201       unsigned int *arr;        /* non-sparse array pointer */
00202       unsigned int arr_sz;      /* array size */
00203       unsigned int bucket_sz;   /* array bucket size */
00204       int pf;                   /* printables */
00205       char **imap;              /* index -> string map */
00206       print_fn_t print_fn;      /* optional user-specified print fn */
00207       unsigned int overflows;   /* total overflows in stat_add_samples() */
00208     } for_dist;
00209     /* sc == sc_sdist */
00210     struct stat_for_sdist_t {
00211       unsigned int init_val;    /* initial dist value */
00212       struct bucket_t **sarr;   /* sparse array pointer */
00213       int pf;                   /* printables */
00214       print_fn_t print_fn;      /* optional user-specified print fn */
00215     } for_sdist;
00216     /* sc == sc_formula */
00217     struct stat_for_formula_t {
00218       char *formula;            /* stat formula, see eval.h for format */
00219     } for_formula;
00220   } variant;
00221 };
00222 
00223 //: statistical database 
00224 //!SEC:ssBack
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              const char *name,          /* stat variable name */
00245              const char *desc,          /* stat variable description */
00246              int *var,                  /* stat variable */
00247              int init_val,              /* stat variable initial value */
00248              const 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               const char *name,         /* stat variable name */
00254               const char *desc,         /* stat variable description */
00255               unsigned int *var,        /* stat variable */
00256               unsigned int init_val,    /* stat variable initial value */
00257               const char *format);              /* optional variable output format */
00258 
00259 #ifdef HOST_HAS_QWORD
00260 /* register a quadword integer statistical variable */
00261 struct stat_stat_t *
00262 stat_reg_quad(struct stat_sdb_t *sdb,   /* stat database */
00263               const char *name,         /* stat variable name */
00264               const char *desc,         /* stat variable description */
00265               qword_t *var,             /* stat variable */
00266               qword_t init_val,         /* stat variable initial value */
00267               const char *format);              /* optional variable output format */
00268 
00269 /* register a signed quadword integer statistical variable */
00270 struct stat_stat_t *
00271 stat_reg_squad(struct stat_sdb_t *sdb,  /* stat database */
00272                const char *name,                /* stat variable name */
00273                const char *desc,                /* stat variable description */
00274                sqword_t *var,           /* stat variable */
00275                sqword_t init_val,       /* stat variable initial value */
00276                const 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                const char *name,                /* stat variable name */
00283                const char *desc,                /* stat variable description */
00284                float *var,              /* stat variable */
00285                float init_val,          /* stat variable initial value */
00286                const 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                 const char *name,               /* stat variable name */
00292                 const char *desc,               /* stat variable description */
00293                 double *var,            /* stat variable */
00294                 double init_val,        /* stat variable initial value */
00295                 const 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                const char *name,                /* stat variable name */
00325                const char *desc,                /* stat variable description */
00326                unsigned int init_val,   /* dist initial value */
00327                int pf,                  /* print format, use PF_* defs */
00328                const 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                  const char *name,              /* stat variable name */
00352                  const char *desc,              /* stat variable description */
00353                  const char *formula,           /* formula expression */
00354                  const 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 #endif /* STAT_H */

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