tools/trace-malloc/stoptions.h

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