options.h

   1 /* options.h - options package interfaces */
   2
   3 /* SimpleScalar(TM) Tool Suite
   4  * Copyright (C) 1994-2003 by Todd M. Austin, Ph.D. and SimpleScalar, LLC.
   5  * All Rights Reserved.
   6  *
   7  * THIS IS A LEGAL DOCUMENT, BY USING SIMPLESCALAR,
   8  * YOU ARE AGREEING TO THESE TERMS AND CONDITIONS.
   9  *
  10  * No portion of this work may be used by any commercial entity, or for any
  11  * commercial purpose, without the prior, written permission of SimpleScalar,
  12  * LLC (info@simplescalar.com). Nonprofit and noncommercial use is permitted
  13  * as described below.
  14  *
  15  * 1. SimpleScalar is provided AS IS, with no warranty of any kind, express
  16  * or implied. The user of the program accepts full responsibility for the
  17  * application of the program and the use of any results.
  18  *
  19  * 2. Nonprofit and noncommercial use is encouraged. SimpleScalar may be
  20  * downloaded, compiled, executed, copied, and modified solely for nonprofit,
  21  * educational, noncommercial research, and noncommercial scholarship
  22  * purposes provided that this notice in its entirety accompanies all copies.
  23  * Copies of the modified software can be delivered to persons who use it
  24  * solely for nonprofit, educational, noncommercial research, and
  25  * noncommercial scholarship purposes provided that this notice in its
  26  * entirety accompanies all copies.
  27  *
  28  * 3. ALL COMMERCIAL USE, AND ALL USE BY FOR PROFIT ENTITIES, IS EXPRESSLY
  29  * PROHIBITED WITHOUT A LICENSE FROM SIMPLESCALAR, LLC (info@simplescalar.com).
  30  *
  31  * 4. No nonprofit user may place any restrictions on the use of this software,
  32  * including as modified by the user, by any other authorized user.
  33  *
  34  * 5. Noncommercial and nonprofit users may distribute copies of SimpleScalar
  35  * in compiled or executable form as set forth in Section 2, provided that
  36  * either: (A) it is accompanied by the corresponding machine-readable source
  37  * code, or (B) it is accompanied by a written offer, with no time limit, to
  38  * give anyone a machine-readable copy of the corresponding source code in
  39  * return for reimbursement of the cost of distribution. This written offer
  40  * must permit verbatim duplication by anyone, or (C) it is distributed by
  41  * someone who received only the executable form, and is accompanied by a
  42  * copy of the written offer of source code.
  43  *
  44  * 6. SimpleScalar was developed by Todd M. Austin, Ph.D. The tool suite is
  45  * currently maintained by SimpleScalar LLC (info@simplescalar.com). US Mail:
  46  * 2395 Timbercrest Court, Ann Arbor, MI 48105.
  47  *
  48  * Copyright (C) 1994-2003 by Todd M. Austin, Ph.D. and SimpleScalar, LLC.
  49  */
  50
  51
  52 #ifndef OPTIONS_H
  53 #define OPTIONS_H
  54
  55 /*
  56  * This options package allows the user to specify the name, description,
  57  * location, and default values of program option variables.  In addition,
  58  * two builtin options are supported:
  59  *
  60  *   -config <filename>         # load options from <filename>
  61  *   -dumpconfig <filename>     # save current option into <filename>
  62  *
  63  * NOTE: all user-installed option names must begin with a `-', e.g., `-debug'
  64  */
  65
  66 /* option variable classes */
  67 enum opt_class_t {
  68   oc_int = 0,           /* integer option */
  69   oc_uint,              /* unsigned integer option */
  70   oc_float,             /* float option */
  71   oc_double,            /* double option */
  72   oc_enum,              /* enumeration option */
  73   oc_flag,              /* boolean option */
  74   oc_string,            /* string option */
  75   oc_NUM
  76 };
  77
  78 /* user-specified option definition */
  79 struct opt_opt_t {
  80   struct opt_opt_t *next;       /* next option */
  81   char *name;                   /* option name, e.g., "-foo:bar" */
  82   char *desc;                   /* option description */
  83   int nvars;                    /* > 1 if var for list options */
  84   int *nelt;                    /* number of elements parsed */
  85   char *format;                 /* option value print format */
  86   int print;                    /* print option during `-dumpconfig'? */
  87   int accrue;                   /* accrue list across uses */
  88   enum opt_class_t oc;          /* class of this option */
  89   union opt_variant_t {
  90     /* oc == oc_int */
  91     struct opt_for_int_t {
  92       int *var;                 /* pointer to integer option */
  93     } for_int;
  94     /* oc == oc_uint */
  95     struct opt_for_uint_t {
  96       unsigned int *var;        /* pointer to unsigned integer option */
  97     } for_uint;
  98     /* oc == oc_float */
  99     struct opt_for_float_t {
 100       float *var;               /* pointer to float option */
 101     } for_float;
 102     /* oc == oc_double */
 103     struct opt_for_double_t {
 104       double *var;              /* pointer to double option */
 105     } for_double;
 106     /* oc == oc_enum, oc_flag */
 107     struct opt_for_enum_t {
 108       int *var;                 /* ptr to *int* enum option, NOTE: AN INT */
 109       char **emap;              /* array of enum strings */
 110       int *eval;                /* optional array of enum values */
 111       int emap_sz;              /* number of enum's in arrays */
 112     } for_enum;
 113     /* oc == oc_string */
 114     struct opt_for_string_t {
 115       char **var;               /* pointer to string pointer option */
 116     } for_string;
 117   } variant;
 118 };
 119
 120 /* user-specified argument orphan parser, called when an argument is
 121    encountered that is not claimed by a user-installed option */
 122 typedef int
 123 (*orphan_fn_t)(int i,           /* index of the orphan'ed argument */
 124                int argc,        /* number of program arguments */
 125                char **argv);    /* program arguments */
 126
 127 /* an option note, these trail the option list when help or option state
 128    is printed */
 129 struct opt_note_t {
 130   struct opt_note_t *next;      /* next option note */
 131   char *note;                   /* option note */
 132 };
 133
 134 /* option database definition */
 135 struct opt_odb_t {
 136   struct opt_opt_t *options;    /* user-installed options in option database */
 137   orphan_fn_t orphan_fn;        /* user-specified orphan parser */
 138   char *header;                 /* options header */
 139   struct opt_note_t *notes;     /* option notes */
 140 };
 141
 142 /* create a new option database */
 143 struct opt_odb_t *
 144 opt_new(orphan_fn_t orphan_fn);         /* user-specified orphan parser */
 145
 146 /* free an option database */
 147 void
 148 opt_delete(struct opt_odb_t *odb);      /* option database */
 149
 150 /* register an integer option variable */
 151 void
 152 opt_reg_int(struct opt_odb_t *odb,      /* option database */
 153             char *name,                 /* option name */
 154             char *desc,                 /* option description */
 155             int *var,                   /* pointer to option variable */
 156             int def_val,                /* default value of option variable */
 157             int print,                  /* print during `-dumpconfig' */
 158             char *format);              /* optional user print format */
 159
 160 /* register an integer option list */
 161 void
 162 opt_reg_int_list(struct opt_odb_t *odb, /* option database */
 163                  char *name,            /* option name */
 164                  char *desc,            /* option description */
 165                  int *vars,             /* pointer to option array */
 166                  int nvars,             /* total entries in option array */
 167                  int *nelt,             /* number of entries parsed */
 168                  int *def_val,          /* default value of option array */
 169                  int print,             /* print during `-dumpconfig'? */
 170                  char *format,          /* optional user print format */
 171                  int accrue);           /* accrue list across uses */
 172
 173 /* register an unsigned integer option variable */
 174 void
 175 opt_reg_uint(struct opt_odb_t *odb,     /* option database */
 176              char *name,                /* option name */
 177              char *desc,                /* option description */
 178              unsigned int *var,         /* pointer to option variable */
 179              unsigned int def_val,      /* default value of option variable */
 180              int print,                 /* print during `-dumpconfig'? */
 181              char *format);             /* optional user print format */
 182
 183 /* register an unsigned integer option list */
 184 void
 185 opt_reg_uint_list(struct opt_odb_t *odb,/* option database */
 186                   char *name,           /* option name */
 187                   char *desc,           /* option description */
 188                   unsigned int *vars,   /* pointer to option array */
 189                   int nvars,            /* total entries in option array */
 190                   int *nelt,            /* number of elements parsed */
 191                   unsigned int *def_val,/* default value of option array */
 192                   int print,            /* print during `-dumpconfig'? */
 193                   char *format,         /* optional user print format */
 194                   int accrue);          /* accrue list across uses */
 195
 196 /* register a single-precision floating point option variable */
 197 void
 198 opt_reg_float(struct opt_odb_t *odb,    /* option data base */
 199               char *name,               /* option name */
 200               char *desc,               /* option description */
 201               float *var,               /* target option variable */
 202               float def_val,            /* default variable value */
 203               int print,                /* print during `-dumpconfig'? */
 204               char *format);            /* optional value print format */
 205
 206 /* register a single-precision floating point option array */
 207 void
 208 opt_reg_float_list(struct opt_odb_t *odb,/* option data base */
 209                    char *name,          /* option name */
 210                    char *desc,          /* option description */
 211                    float *vars,         /* target array */
 212                    int nvars,           /* target array size */
 213                    int *nelt,           /* number of args parsed goes here */
 214                    float *def_val,      /* default variable value */
 215                    int print,           /* print during `-dumpconfig'? */
 216                    char *format,        /* optional value print format */
 217                    int accrue);         /* accrue list across uses */
 218
 219 /* register a double-precision floating point option variable */
 220 void
 221 opt_reg_double(struct opt_odb_t *odb,   /* option data base */
 222                char *name,              /* option name */
 223                char *desc,              /* option description */
 224                double *var,             /* target variable */
 225                double def_val,          /* default variable value */
 226                int print,               /* print during `-dumpconfig'? */
 227                char *format);           /* optional value print format */
 228
 229 /* register a double-precision floating point option array */
 230 void
 231 opt_reg_double_list(struct opt_odb_t *odb,/* option data base */
 232                     char *name,         /* option name */
 233                     char *desc,         /* option description */
 234                     double *vars,       /* target array */
 235                     int nvars,          /* target array size */
 236                     int *nelt,          /* number of args parsed goes here */
 237                     double *def_val,    /* default variable value */
 238                     int print,          /* print during `-dumpconfig'? */
 239                     char *format,       /* optional value print format */
 240                     int accrue);        /* accrue list across uses */
 241
 242 /* register an enumeration option variable, NOTE: all enumeration option
 243    variables must be of type `int', since true enum variables may be allocated
 244    with variable sizes by some compilers */
 245 void
 246 opt_reg_enum(struct opt_odb_t *odb,     /* option data base */
 247              char *name,                /* option name */
 248              char *desc,                /* option description */
 249              int *var,                  /* target variable */
 250              char *def_val,             /* default variable value */
 251              char **emap,               /* enumeration string map */
 252              int *eval,                 /* enumeration value map, optional */
 253              int emap_sz,               /* size of maps */
 254              int print,                 /* print during `-dumpconfig'? */
 255              char *format);             /* optional value print format */
 256
 257 /* register an enumeration option array, NOTE: all enumeration option variables
 258    must be of type `int', since true enum variables may be allocated with
 259    variable sizes by some compilers */
 260 void
 261 opt_reg_enum_list(struct opt_odb_t *odb,/* option data base */
 262                   char *name,           /* option name */
 263                   char *desc,           /* option description */
 264                   int *vars,            /* target array */
 265                   int nvars,            /* target array size */
 266                   int *nelt,            /* number of args parsed goes here */
 267                   char *def_val,        /* default variable value */
 268                   char **emap,          /* enumeration string map */
 269                   int *eval,            /* enumeration value map, optional */
 270                   int emap_sz,          /* size of maps */
 271                   int print,            /* print during `-dumpconfig'? */
 272                   char *format,         /* optional value print format */
 273                   int accrue);          /* accrue list across uses */
 274
 275 /* register a boolean flag option variable */
 276 void
 277 opt_reg_flag(struct opt_odb_t *odb,     /* option data base */
 278              char *name,                /* option name */
 279              char *desc,                /* option description */
 280              int *var,                  /* target variable */
 281              int def_val,               /* default variable value */
 282              int print,                 /* print during `-dumpconfig'? */
 283              char *format);             /* optional value print format */
 284
 285 /* register a boolean flag option array */
 286 void
 287 opt_reg_flag_list(struct opt_odb_t *odb,/* option database */
 288                   char *name,           /* option name */
 289                   char *desc,           /* option description */
 290                   int *vars,            /* pointer to option array */
 291                   int nvars,            /* total entries in option array */
 292                   int *nelt,            /* number of elements parsed */
 293                   int *def_val,         /* default array value */
 294                   int print,            /* print during `-dumpconfig'? */
 295                   char *format,         /* optional value print format */
 296                   int accrue);          /* accrue list across uses */
 297
 298 /* register a string option variable */
 299 void
 300 opt_reg_string(struct opt_odb_t *odb,   /* option data base */
 301                char *name,              /* option name */
 302                char *desc,              /* option description */
 303                char **var,              /* pointer to string option variable */
 304                char *def_val,           /* default variable value */
 305                int print,               /* print during `-dumpconfig'? */
 306                char *format);           /* optional value print format */
 307
 308 /* register a string option array */
 309 void
 310 opt_reg_string_list(struct opt_odb_t *odb,/* option data base */
 311                     char *name,         /* option name */
 312                     char *desc,         /* option description */
 313                     char **vars,        /* pointer to option string array */
 314                     int nvars,          /* target array size */
 315                     int *nelt,          /* number of args parsed goes here */
 316                     char **def_val,     /* default variable value */
 317                     int print,          /* print during `-dumpconfig'? */
 318                     char *format,       /* optional value print format */
 319                     int accrue);        /* accrue list across uses */
 320
 321 /* process command line arguments */
 322 void
 323 opt_process_options(struct opt_odb_t *odb,      /* option data base */
 324                     int argc,                   /* number of arguments */
 325                     char **argv);               /* argument array */
 326
 327 /* print the value of an option */
 328 void
 329 opt_print_option(struct opt_opt_t *opt, /* option variable */
 330                  FILE *fd);             /* output stream */
 331
 332 /* print all options and current values */
 333 void
 334 opt_print_options(struct opt_odb_t *odb,/* option data base */
 335                   FILE *fd,             /* output stream */
 336                   int terse,            /* print terse options? */
 337                   int notes);           /* include notes? */
 338
 339 /* print option help page with default values */
 340 void
 341 opt_print_help(struct opt_odb_t *odb,   /* option data base */
 342                FILE *fd);               /* output stream */
 343
 344 /* find an option by name in the option database, returns NULL if not found */
 345 struct opt_opt_t *
 346 opt_find_option(struct opt_odb_t *odb,  /* option database */
 347                 char *opt_name);        /* option name */
 348
 349 /* register an options header, the header is printed before the option list */
 350 void
 351 opt_reg_header(struct opt_odb_t *odb,   /* option database */
 352                char *header);           /* options header string */
 353
 354 /* register an option note, notes are printed after the list of options */
 355 void
 356 opt_reg_note(struct opt_odb_t *odb,     /* option database */
 357              char *note);               /* option note */
 358
 359 #endif /* OPTIONS_H */