1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/tools/trace-malloc/stoptions.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,302 @@
1.4 +/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
1.5 + *
1.6 + * This Source Code Form is subject to the terms of the Mozilla Public
1.7 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.8 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.9 +
1.10 +/*
1.11 +** stoptions.h
1.12 +**
1.13 +** Abstract the spacetrace options into a reusable format, such that
1.14 +** many different pieces of the code can utilize the common list.
1.15 +*/
1.16 +
1.17 +/*
1.18 +** There are three types of options.
1.19 +** The destinction is quite important.
1.20 +**
1.21 +** CMD options are accessible from only the comamnd line.
1.22 +** Such options should be considered global/static for the entire
1.23 +** run of the application.
1.24 +** Once set, no one can change these options during the run.
1.25 +**
1.26 +** WEB options are accessible from the web server options page.
1.27 +** Such options can and will be changed on a per user basis during
1.28 +** the run of the application.
1.29 +** You should NEVER make an option a WEB only option, as this will
1.30 +** break batch mode processing, and will likely not correctly
1.31 +** define the options structure itself.
1.32 +** These options will control the data caching used in the application
1.33 +** to match a client to a cache of data.
1.34 +**
1.35 +** ALL options are both CMD and WEB options, with the properties of WEB
1.36 +** options (the user will change these on a per client basis).
1.37 +** Most likely this is the type of option you will desire to create.
1.38 +*/
1.39 +
1.40 +/*
1.41 +** All types of options have some combination of the following elements:
1.42 +**
1.43 +** option_name The name of the option.
1.44 +** option_genre Area the option effects; STOptionGenre.
1.45 +** default_value The default value for the option.
1.46 +** array_size Used to size a string array.
1.47 +** multiplier Some numbers prefer conversion.
1.48 +** option_help Help text to explain the option.
1.49 +**
1.50 +** NOTE! that the multiplier should be applied to the default value if you
1.51 +** are going to assign the default_value into anything.
1.52 +**
1.53 +** Be very aware that adding things to a particular genre, or adding a genre,
1.54 +** may completely screw up the caching algorithms of SpaceTrace.
1.55 +** See contextLookup() or ask someone that knows if you are in doubt.
1.56 +**
1.57 +** The actual definition of the WEB and CMD macros however is left to the
1.58 +** end user.
1.59 +** We cover those that you do not define herein.
1.60 +*/
1.61 +#if !defined(ST_CMD_OPTION_BOOL)
1.62 +#define ST_CMD_OPTION_BOOL(option_name, option_genre, option_help)
1.63 +#endif
1.64 +#if !defined(ST_WEB_OPTION_BOOL)
1.65 +#define ST_WEB_OPTION_BOOL(option_name, option_genre, option_help)
1.66 +#endif
1.67 +#if !defined(ST_CMD_OPTION_STRING)
1.68 +#define ST_CMD_OPTION_STRING(option_name, option_genre, default_value, option_help)
1.69 +#endif
1.70 +#if !defined(ST_WEB_OPTION_STRING)
1.71 +#define ST_WEB_OPTION_STRING(option_name, option_genre, default_value, option_help)
1.72 +#endif
1.73 +#if !defined(ST_CMD_OPTION_STRING_ARRAY)
1.74 +#define ST_CMD_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help)
1.75 +#endif
1.76 +#if !defined(ST_WEB_OPTION_STRING_ARRAY)
1.77 +#define ST_WEB_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help)
1.78 +#endif
1.79 +#if !defined(ST_CMD_OPTION_STRING_PTR_ARRAY)
1.80 +#define ST_CMD_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help)
1.81 +#endif
1.82 +#if !defined(ST_WEB_OPTION_STRING_PTR_ARRAY)
1.83 +#define ST_WEB_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help)
1.84 +#endif
1.85 +#if !defined(ST_CMD_OPTION_UINT32)
1.86 +#define ST_CMD_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help)
1.87 +#endif
1.88 +#if !defined(ST_WEB_OPTION_UINT32)
1.89 +#define ST_WEB_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help)
1.90 +#endif
1.91 +#if !defined(ST_CMD_OPTION_UINT64)
1.92 +#define ST_CMD_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help)
1.93 +#endif
1.94 +#if !defined(ST_WEB_OPTION_UINT64)
1.95 +#define ST_WEB_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help)
1.96 +#endif
1.97 +
1.98 +/*
1.99 +** ALL macros expand to both CMD and WEB macros.
1.100 +** This basically means such options are accessible from both the command
1.101 +** line and from the web options.
1.102 +*/
1.103 +#define ST_ALL_OPTION_BOOL(option_name, option_genre, option_help) \
1.104 + ST_CMD_OPTION_BOOL(option_name, option_genre, option_help) \
1.105 + ST_WEB_OPTION_BOOL(option_name, option_genre, option_help)
1.106 +#define ST_ALL_OPTION_STRING(option_name, option_genre, default_value, option_help) \
1.107 + ST_CMD_OPTION_STRING(option_name, option_genre, default_value, option_help) \
1.108 + ST_WEB_OPTION_STRING(option_name, option_genre, default_value, option_help)
1.109 +#define ST_ALL_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help) \
1.110 + ST_CMD_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help) \
1.111 + ST_WEB_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help)
1.112 +#define ST_ALL_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help) \
1.113 + ST_CMD_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help) \
1.114 + ST_WEB_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help)
1.115 +#define ST_ALL_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help) \
1.116 + ST_CMD_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help) \
1.117 + ST_WEB_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help)
1.118 +#define ST_ALL_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help) \
1.119 + ST_CMD_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help) \
1.120 + ST_WEB_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help)
1.121 +
1.122 +
1.123 +
1.124 +/****************************************************************************
1.125 +** BEGIN, THE OPTIONS
1.126 +**
1.127 +** Order is somewhat relevant in that it will control 3 different things:
1.128 +** 1) The order the members will be in the options structure.
1.129 +** 2) The order the options are presented on the command line.
1.130 +** 3) The order the options are presented on the web options page.
1.131 +*/
1.132 +
1.133 +ST_ALL_OPTION_STRING(CategoryName,
1.134 + CategoryGenre,
1.135 + ST_ROOT_CATEGORY_NAME,
1.136 + "Specify a category for reports to focus upon.\n"
1.137 + "See http://lxr.mozilla.org/mozilla/source/tools/trace-malloc/rules.txt\n")
1.138 +
1.139 +ST_ALL_OPTION_UINT32(OrderBy,
1.140 + DataSortGenre,
1.141 + ST_SIZE, /* for dp :-D */
1.142 + 1,
1.143 + "Determine the sort order.\n"
1.144 + "0 by weight (size * lifespan).\n"
1.145 + "1 by size.\n"
1.146 + "2 by lifespan.\n"
1.147 + "3 by allocation count.\n"
1.148 + "4 by performance cost.\n")
1.149 +
1.150 +ST_ALL_OPTION_STRING_ARRAY(RestrictText,
1.151 + DataSetGenre,
1.152 + ST_SUBSTRING_MATCH_MAX,
1.153 + "Exclude allocations which do not have this text in their backtrace.\n"
1.154 + "Multiple restrictions are treated as a logical AND operation.\n")
1.155 +
1.156 +ST_ALL_OPTION_UINT32(SizeMin,
1.157 + DataSetGenre,
1.158 + 0,
1.159 + 1,
1.160 + "Exclude allocations that are below this byte size.\n")
1.161 +
1.162 +ST_ALL_OPTION_UINT32(SizeMax,
1.163 + DataSetGenre,
1.164 + 0xFFFFFFFF,
1.165 + 1,
1.166 + "Exclude allocations that are above this byte size.\n")
1.167 +
1.168 +ST_ALL_OPTION_UINT32(LifetimeMin,
1.169 + DataSetGenre,
1.170 + ST_DEFAULT_LIFETIME_MIN,
1.171 + ST_TIMEVAL_RESOLUTION,
1.172 + "Allocations must live this number of seconds or be ignored.\n")
1.173 +
1.174 +ST_ALL_OPTION_UINT32(LifetimeMax,
1.175 + DataSetGenre,
1.176 + ST_TIMEVAL_MAX / ST_TIMEVAL_RESOLUTION,
1.177 + ST_TIMEVAL_RESOLUTION,
1.178 + "Allocations living longer than this number of seconds will be ignored.\n")
1.179 +
1.180 +ST_ALL_OPTION_UINT32(TimevalMin,
1.181 + DataSetGenre,
1.182 + 0,
1.183 + ST_TIMEVAL_RESOLUTION,
1.184 + "Allocations existing solely before this second will be ignored.\n"
1.185 + "Live allocations at this second and after can be considered.\n")
1.186 +
1.187 +ST_ALL_OPTION_UINT32(TimevalMax,
1.188 + DataSetGenre,
1.189 + ST_TIMEVAL_MAX / ST_TIMEVAL_RESOLUTION,
1.190 + ST_TIMEVAL_RESOLUTION,
1.191 + "Allocations existing solely after this second will be ignored.\n"
1.192 + "Live allocations at this second and before can be considered.\n")
1.193 +
1.194 +ST_ALL_OPTION_UINT32(AllocationTimevalMin,
1.195 + DataSetGenre,
1.196 + 0,
1.197 + ST_TIMEVAL_RESOLUTION,
1.198 + "Live and dead allocations created before this second will be ignored.\n")
1.199 +
1.200 +ST_ALL_OPTION_UINT32(AllocationTimevalMax,
1.201 + DataSetGenre,
1.202 + ST_TIMEVAL_MAX / ST_TIMEVAL_RESOLUTION,
1.203 + ST_TIMEVAL_RESOLUTION,
1.204 + "Live and dead allocations created after this second will be ignored.\n")
1.205 +
1.206 +ST_ALL_OPTION_UINT32(AlignBy,
1.207 + DataSizeGenre,
1.208 + ST_DEFAULT_ALIGNMENT_SIZE,
1.209 + 1,
1.210 + "All allocation sizes are made to be a multiple of this number.\n"
1.211 + "Closer to actual heap conditions; set to 1 for true sizes.\n")
1.212 +
1.213 +ST_ALL_OPTION_UINT32(Overhead,
1.214 + DataSizeGenre,
1.215 + ST_DEFAULT_OVERHEAD_SIZE,
1.216 + 1,
1.217 + "After alignment, all allocations are made to increase by this number.\n"
1.218 + "Closer to actual heap conditions; set to 0 for true sizes.\n")
1.219 +
1.220 +ST_ALL_OPTION_UINT32(ListItemMax,
1.221 + UIGenre,
1.222 + 500,
1.223 + 1,
1.224 + "Specifies the maximum number of list items to present in each list.\n")
1.225 +
1.226 +ST_ALL_OPTION_UINT64(WeightMin,
1.227 + DataSetGenre,
1.228 + 0,
1.229 + 1,
1.230 + "Exclude allocations that are below this weight (lifespan * size).\n")
1.231 +
1.232 +ST_ALL_OPTION_UINT64(WeightMax,
1.233 + DataSetGenre,
1.234 + (0xFFFFFFFFLL << 32) + 0xFFFFFFFFLL,
1.235 + 1,
1.236 + "Exclude allocations that are above this weight (lifespan * size).\n")
1.237 +
1.238 +ST_CMD_OPTION_STRING(FileName,
1.239 + DataSetGenre,
1.240 + "-",
1.241 + "Specifies trace-malloc input file.\n"
1.242 + "\"-\" indicates stdin will be used as input.\n")
1.243 +
1.244 +ST_CMD_OPTION_STRING(CategoryFile,
1.245 + CategoryGenre,
1.246 + "rules.txt",
1.247 + "Specifies the category rules file.\n"
1.248 + "This file contains rules about how to categorize allocations.\n")
1.249 +
1.250 +
1.251 +ST_CMD_OPTION_UINT32(HttpdPort,
1.252 + ServerGenre,
1.253 + 1969,
1.254 + 1,
1.255 + "Specifies the default port the web server will listen on.\n")
1.256 +
1.257 +ST_CMD_OPTION_STRING(OutputDir,
1.258 + BatchModeGenre,
1.259 + ".",
1.260 + "Specifies a directory to output batch mode requests.\n"
1.261 + "The directory must exist and must not use a trailing slash.\n")
1.262 +
1.263 +ST_CMD_OPTION_STRING_PTR_ARRAY(BatchRequest,
1.264 + BatchModeGenre,
1.265 + "This implicitly turns on batch mode.\n"
1.266 + "Save each requested file into the output dir, then exit.\n")
1.267 +
1.268 +ST_CMD_OPTION_UINT32(Contexts,
1.269 + ServerGenre,
1.270 + 1,
1.271 + 1,
1.272 + "How many configurations to cache at the cost of a lot of memory.\n"
1.273 + "Dedicated servers can cache more client configurations for performance.\n")
1.274 +
1.275 +ST_CMD_OPTION_BOOL(Help,
1.276 + UIGenre,
1.277 + "Show command line help.\n"
1.278 + "See http://www.mozilla.org/projects/footprint/spaceTrace.html\n")
1.279 +
1.280 +/*
1.281 +** END, THE OPTIONS
1.282 +****************************************************************************/
1.283 +
1.284 +/*
1.285 +** Everything is undefined after the header is included.
1.286 +** This sets it up for multiple inclusion if so desired.
1.287 +*/
1.288 +#undef ST_ALL_OPTION_BOOL
1.289 +#undef ST_CMD_OPTION_BOOL
1.290 +#undef ST_WEB_OPTION_BOOL
1.291 +#undef ST_ALL_OPTION_STRING
1.292 +#undef ST_CMD_OPTION_STRING
1.293 +#undef ST_WEB_OPTION_STRING
1.294 +#undef ST_ALL_OPTION_STRING_ARRAY
1.295 +#undef ST_CMD_OPTION_STRING_ARRAY
1.296 +#undef ST_WEB_OPTION_STRING_ARRAY
1.297 +#undef ST_ALL_OPTION_STRING_PTR_ARRAY
1.298 +#undef ST_CMD_OPTION_STRING_PTR_ARRAY
1.299 +#undef ST_WEB_OPTION_STRING_PTR_ARRAY
1.300 +#undef ST_ALL_OPTION_UINT32
1.301 +#undef ST_CMD_OPTION_UINT32
1.302 +#undef ST_WEB_OPTION_UINT32
1.303 +#undef ST_ALL_OPTION_UINT64
1.304 +#undef ST_CMD_OPTION_UINT64
1.305 +#undef ST_WEB_OPTION_UINT64
