tools/trace-malloc/stoptions.h

   1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
   2  *
   3  * ***** BEGIN LICENSE BLOCK *****
   4  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   5  *
   6  * The contents of this file are subject to the Mozilla Public License Version
   7  * 1.1 (the "License"); you may not use this file except in compliance with
   8  * the License. You may obtain a copy of the License at
   9  * http://www.mozilla.org/MPL/
  10  *
  11  * Software distributed under the License is distributed on an "AS IS" basis,
  12  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13  * for the specific language governing rights and limitations under the
  14  * License.
  15  *
  16  * The Original Code is stoptions.h code, released
  17  * May 7, 2002.
  18  *
  19  * The Initial Developer of the Original Code is
  20  * Netscape Communications Corporation.
  21  * Portions created by the Initial Developer are Copyright (C) 2002
  22  * the Initial Developer. All Rights Reserved.
  23  *
  24  * Contributor(s):
  25  *   Garrett Arch Blythe, 07-May-2002
  26  *
  27  * Alternatively, the contents of this file may be used under the terms of
  28  * either the GNU General Public License Version 2 or later (the "GPL"), or
  29  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30  * in which case the provisions of the GPL or the LGPL are applicable instead
  31  * of those above. If you wish to allow use of your version of this file only
  32  * under the terms of either the GPL or the LGPL, and not to allow others to
  33  * use your version of this file under the terms of the MPL, indicate your
  34  * decision by deleting the provisions above and replace them with the notice
  35  * and other provisions required by the GPL or the LGPL. If you do not delete
  36  * the provisions above, a recipient may use your version of this file under
  37  * the terms of any one of the MPL, the GPL or the LGPL.
  38  *
  39  * ***** END LICENSE BLOCK ***** */
  40
  41 /*
  42 **  stoptions.h
  43 **
  44 **  Abstract the spacetrace options into a reusable format, such that
  45 **      many different pieces of the code can utilize the common list.
  46 */
  47
  48 /*
  49 **  There are three types of options.
  50 **  The destinction is quite important.
  51 **
  52 **  CMD options are accessible from only the comamnd line.
  53 **      Such options should be considered global/static for the entire
  54 **          run of the application.
  55 **      Once set, no one can change these options during the run.
  56 **
  57 **  WEB options are accessible from the web server options page.
  58 **      Such options can and will be changed on a per user basis during
  59 **          the run of the application.
  60 **      You should NEVER make an option a WEB only option, as this will
  61 **          break batch mode processing, and will likely not correctly
  62 **          define the options structure itself.
  63 **      These options will control the data caching used in the application
  64 **          to match a client to a cache of data.
  65 **
  66 **  ALL options are both CMD and WEB options, with the properties of WEB
  67 **      options (the user will change these on a per client basis).
  68 **      Most likely this is the type of option you will desire to create.
  69 */
  70
  71 /*
  72 **  All types of options have some combination of the following elements:
  73 **
  74 **  option_name             The name of the option.
  75 **  option_genre            Area the option effects; STOptionGenre.
  76 **  default_value           The default value for the option.
  77 **  array_size              Used to size a string array.
  78 **  multiplier              Some numbers prefer conversion.
  79 **  option_help             Help text to explain the option.
  80 **
  81 **  NOTE! that the multiplier should be applied to the default value if you
  82 **      are going to assign the default_value into anything.
  83 **
  84 **  Be very aware that adding things to a particular genre, or adding a genre,
  85 **      may completely screw up the caching algorithms of SpaceTrace.
  86 **  See contextLookup() or ask someone that knows if you are in doubt.
  87 **
  88 **  The actual definition of the WEB and CMD macros however is left to the
  89 **      end user.
  90 **  We cover those that you do not define herein.
  91 */
  92 #if !defined(ST_CMD_OPTION_BOOL)
  93 #define ST_CMD_OPTION_BOOL(option_name, option_genre, option_help)
  94 #endif
  95 #if !defined(ST_WEB_OPTION_BOOL)
  96 #define ST_WEB_OPTION_BOOL(option_name, option_genre, option_help)
  97 #endif
  98 #if !defined(ST_CMD_OPTION_STRING)
  99 #define ST_CMD_OPTION_STRING(option_name, option_genre, default_value, option_help)
 100 #endif
 101 #if !defined(ST_WEB_OPTION_STRING)
 102 #define ST_WEB_OPTION_STRING(option_name, option_genre, default_value, option_help)
 103 #endif
 104 #if !defined(ST_CMD_OPTION_STRING_ARRAY)
 105 #define ST_CMD_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help)
 106 #endif
 107 #if !defined(ST_WEB_OPTION_STRING_ARRAY)
 108 #define ST_WEB_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help)
 109 #endif
 110 #if !defined(ST_CMD_OPTION_STRING_PTR_ARRAY)
 111 #define ST_CMD_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help)
 112 #endif
 113 #if !defined(ST_WEB_OPTION_STRING_PTR_ARRAY)
 114 #define ST_WEB_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help)
 115 #endif
 116 #if !defined(ST_CMD_OPTION_UINT32)
 117 #define ST_CMD_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help)
 118 #endif
 119 #if !defined(ST_WEB_OPTION_UINT32)
 120 #define ST_WEB_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help)
 121 #endif
 122 #if !defined(ST_CMD_OPTION_UINT64)
 123 #define ST_CMD_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help)
 124 #endif
 125 #if !defined(ST_WEB_OPTION_UINT64)
 126 #define ST_WEB_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help)
 127 #endif
 128
 129 /*
 130 **  ALL macros expand to both CMD and WEB macros.
 131 **  This basically means such options are accessible from both the command
 132 **      line and from the web options.
 133 */
 134 #define ST_ALL_OPTION_BOOL(option_name, option_genre, option_help) \
 135     ST_CMD_OPTION_BOOL(option_name, option_genre, option_help) \
 136     ST_WEB_OPTION_BOOL(option_name, option_genre, option_help)
 137 #define ST_ALL_OPTION_STRING(option_name, option_genre, default_value, option_help) \
 138     ST_CMD_OPTION_STRING(option_name, option_genre, default_value, option_help) \
 139     ST_WEB_OPTION_STRING(option_name, option_genre, default_value, option_help)
 140 #define ST_ALL_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help) \
 141     ST_CMD_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help) \
 142     ST_WEB_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help)
 143 #define ST_ALL_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help) \
 144     ST_CMD_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help) \
 145     ST_WEB_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help)
 146 #define ST_ALL_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help) \
 147     ST_CMD_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help) \
 148     ST_WEB_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help)
 149 #define ST_ALL_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help) \
 150     ST_CMD_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help) \
 151     ST_WEB_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help)
 152
 153
 154
 155 /****************************************************************************
 156 **  BEGIN, THE OPTIONS
 157 **
 158 **  Order is somewhat relevant in that it will control 3 different things:
 159 **      1)  The order the members will be in the options structure.
 160 **      2)  The order the options are presented on the command line.
 161 **      3)  The order the options are presented on the web options page.
 162 */
 163
 164 ST_ALL_OPTION_STRING(CategoryName,
 165                      CategoryGenre,
 166                      ST_ROOT_CATEGORY_NAME,
 167                      "Specify a category for reports to focus upon.\n"
 168                      "See http://lxr.mozilla.org/mozilla/source/tools/trace-malloc/rules.txt\n")
 169
 170 ST_ALL_OPTION_UINT32(OrderBy,
 171                      DataSortGenre,
 172                      ST_SIZE, /* for dp :-D */
 173                      1,
 174                      "Determine the sort order.\n"
 175                      "0 by weight (size * lifespan).\n"
 176                      "1 by size.\n"
 177                      "2 by lifespan.\n"
 178                      "3 by allocation count.\n"
 179                      "4 by performance cost.\n")
 180
 181 ST_ALL_OPTION_STRING_ARRAY(RestrictText,
 182                            DataSetGenre,
 183                            ST_SUBSTRING_MATCH_MAX,
 184                            "Exclude allocations which do not have this text in their backtrace.\n"
 185                            "Multiple restrictions are treated as a logical AND operation.\n")
 186
 187 ST_ALL_OPTION_UINT32(SizeMin,
 188                      DataSetGenre,
 189                      0,
 190                      1,
 191                      "Exclude allocations that are below this byte size.\n")
 192
 193 ST_ALL_OPTION_UINT32(SizeMax,
 194                      DataSetGenre,
 195                      0xFFFFFFFF,
 196                      1,
 197                      "Exclude allocations that are above this byte size.\n")
 198
 199 ST_ALL_OPTION_UINT32(LifetimeMin,
 200                      DataSetGenre,
 201                      ST_DEFAULT_LIFETIME_MIN,
 202                      ST_TIMEVAL_RESOLUTION,
 203                      "Allocations must live this number of seconds or be ignored.\n")
 204
 205 ST_ALL_OPTION_UINT32(LifetimeMax,
 206                      DataSetGenre,
 207                      ST_TIMEVAL_MAX / ST_TIMEVAL_RESOLUTION,
 208                      ST_TIMEVAL_RESOLUTION,
 209                      "Allocations living longer than this number of seconds will be ignored.\n")
 210
 211 ST_ALL_OPTION_UINT32(TimevalMin,
 212                      DataSetGenre,
 213                      0,
 214                      ST_TIMEVAL_RESOLUTION,
 215                      "Allocations existing solely before this second will be ignored.\n"
 216                      "Live allocations at this second and after can be considered.\n")
 217
 218 ST_ALL_OPTION_UINT32(TimevalMax,
 219                      DataSetGenre,
 220                      ST_TIMEVAL_MAX / ST_TIMEVAL_RESOLUTION,
 221                      ST_TIMEVAL_RESOLUTION,
 222                      "Allocations existing solely after this second will be ignored.\n"
 223                      "Live allocations at this second and before can be considered.\n")
 224
 225 ST_ALL_OPTION_UINT32(AllocationTimevalMin,
 226                      DataSetGenre,
 227                      0,
 228                      ST_TIMEVAL_RESOLUTION,
 229                      "Live and dead allocations created before this second will be ignored.\n")
 230
 231 ST_ALL_OPTION_UINT32(AllocationTimevalMax,
 232                      DataSetGenre,
 233                      ST_TIMEVAL_MAX / ST_TIMEVAL_RESOLUTION,
 234                      ST_TIMEVAL_RESOLUTION,
 235                      "Live and dead allocations created after this second will be ignored.\n")
 236
 237 ST_ALL_OPTION_UINT32(AlignBy,
 238                      DataSizeGenre,
 239                      ST_DEFAULT_ALIGNMENT_SIZE,
 240                      1,
 241                      "All allocation sizes are made to be a multiple of this number.\n"
 242                      "Closer to actual heap conditions; set to 1 for true sizes.\n")
 243
 244 ST_ALL_OPTION_UINT32(Overhead,
 245                      DataSizeGenre,
 246                      ST_DEFAULT_OVERHEAD_SIZE,
 247                      1,
 248                      "After alignment, all allocations are made to increase by this number.\n"
 249                      "Closer to actual heap conditions; set to 0 for true sizes.\n")
 250
 251 ST_ALL_OPTION_UINT32(ListItemMax,
 252                      UIGenre,
 253                      500,
 254                      1,
 255                      "Specifies the maximum number of list items to present in each list.\n")
 256
 257 ST_ALL_OPTION_UINT64(WeightMin,
 258                      DataSetGenre,
 259                      LL_INIT(0, 0),
 260                      LL_INIT(0, 1),
 261                      "Exclude allocations that are below this weight (lifespan * size).\n")
 262
 263 ST_ALL_OPTION_UINT64(WeightMax,
 264                      DataSetGenre,
 265                      LL_INIT(0xFFFFFFFF, 0xFFFFFFFF),
 266                      LL_INIT(0, 1),
 267                      "Exclude allocations that are above this weight (lifespan * size).\n")
 268
 269 ST_CMD_OPTION_STRING(FileName,
 270                      DataSetGenre,
 271                      "-",
 272                      "Specifies trace-malloc input file.\n"
 273                      "\"-\" indicates stdin will be used as input.\n")
 274
 275 ST_CMD_OPTION_STRING(CategoryFile,
 276                      CategoryGenre,
 277                      "rules.txt",
 278                      "Specifies the category rules file.\n"
 279                      "This file contains rules about how to categorize allocations.\n")
 280
 281
 282 ST_CMD_OPTION_UINT32(HttpdPort,
 283                      ServerGenre,
 284                      1969,
 285                      1,
 286                      "Specifies the default port the web server will listen on.\n")
 287
 288 ST_CMD_OPTION_STRING(OutputDir,
 289                      BatchModeGenre,
 290                      ".",
 291                      "Specifies a directory to output batch mode requests.\n"
 292                      "The directory must exist and must not use a trailing slash.\n")
 293
 294 ST_CMD_OPTION_STRING_PTR_ARRAY(BatchRequest,
 295                                BatchModeGenre,
 296                                "This implicitly turns on batch mode.\n"
 297                                "Save each requested file into the output dir, then exit.\n")
 298
 299 ST_CMD_OPTION_UINT32(Contexts,
 300                      ServerGenre,
 301                      1,
 302                      1,
 303                      "How many configurations to cache at the cost of a lot of memory.\n"
 304                      "Dedicated servers can cache more client configurations for performance.\n")
 305
 306 ST_CMD_OPTION_BOOL(Help,
 307                    UIGenre,
 308                    "Show command line help.\n"
 309                    "See http://www.mozilla.org/projects/footprint/spaceTrace.html\n")
 310
 311 /*
 312 **  END, THE OPTIONS
 313 ****************************************************************************/
 314
 315 /*
 316 **  Everything is undefined after the header is included.
 317 **  This sets it up for multiple inclusion if so desired.
 318 */
 319 #undef ST_ALL_OPTION_BOOL
 320 #undef ST_CMD_OPTION_BOOL
 321 #undef ST_WEB_OPTION_BOOL
 322 #undef ST_ALL_OPTION_STRING
 323 #undef ST_CMD_OPTION_STRING
 324 #undef ST_WEB_OPTION_STRING
 325 #undef ST_ALL_OPTION_STRING_ARRAY
 326 #undef ST_CMD_OPTION_STRING_ARRAY
 327 #undef ST_WEB_OPTION_STRING_ARRAY
 328 #undef ST_ALL_OPTION_STRING_PTR_ARRAY
 329 #undef ST_CMD_OPTION_STRING_PTR_ARRAY
 330 #undef ST_WEB_OPTION_STRING_PTR_ARRAY
 331 #undef ST_ALL_OPTION_UINT32
 332 #undef ST_CMD_OPTION_UINT32
 333 #undef ST_WEB_OPTION_UINT32
 334 #undef ST_ALL_OPTION_UINT64
 335 #undef ST_CMD_OPTION_UINT64
 336 #undef ST_WEB_OPTION_UINT64