michael@0: /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*- michael@0: * michael@0: * This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: /* michael@0: ** stoptions.h michael@0: ** michael@0: ** Abstract the spacetrace options into a reusable format, such that michael@0: ** many different pieces of the code can utilize the common list. michael@0: */ michael@0: michael@0: /* michael@0: ** There are three types of options. michael@0: ** The destinction is quite important. michael@0: ** michael@0: ** CMD options are accessible from only the comamnd line. michael@0: ** Such options should be considered global/static for the entire michael@0: ** run of the application. michael@0: ** Once set, no one can change these options during the run. michael@0: ** michael@0: ** WEB options are accessible from the web server options page. michael@0: ** Such options can and will be changed on a per user basis during michael@0: ** the run of the application. michael@0: ** You should NEVER make an option a WEB only option, as this will michael@0: ** break batch mode processing, and will likely not correctly michael@0: ** define the options structure itself. michael@0: ** These options will control the data caching used in the application michael@0: ** to match a client to a cache of data. michael@0: ** michael@0: ** ALL options are both CMD and WEB options, with the properties of WEB michael@0: ** options (the user will change these on a per client basis). michael@0: ** Most likely this is the type of option you will desire to create. michael@0: */ michael@0: michael@0: /* michael@0: ** All types of options have some combination of the following elements: michael@0: ** michael@0: ** option_name The name of the option. michael@0: ** option_genre Area the option effects; STOptionGenre. michael@0: ** default_value The default value for the option. michael@0: ** array_size Used to size a string array. michael@0: ** multiplier Some numbers prefer conversion. michael@0: ** option_help Help text to explain the option. michael@0: ** michael@0: ** NOTE! that the multiplier should be applied to the default value if you michael@0: ** are going to assign the default_value into anything. michael@0: ** michael@0: ** Be very aware that adding things to a particular genre, or adding a genre, michael@0: ** may completely screw up the caching algorithms of SpaceTrace. michael@0: ** See contextLookup() or ask someone that knows if you are in doubt. michael@0: ** michael@0: ** The actual definition of the WEB and CMD macros however is left to the michael@0: ** end user. michael@0: ** We cover those that you do not define herein. michael@0: */ michael@0: #if !defined(ST_CMD_OPTION_BOOL) michael@0: #define ST_CMD_OPTION_BOOL(option_name, option_genre, option_help) michael@0: #endif michael@0: #if !defined(ST_WEB_OPTION_BOOL) michael@0: #define ST_WEB_OPTION_BOOL(option_name, option_genre, option_help) michael@0: #endif michael@0: #if !defined(ST_CMD_OPTION_STRING) michael@0: #define ST_CMD_OPTION_STRING(option_name, option_genre, default_value, option_help) michael@0: #endif michael@0: #if !defined(ST_WEB_OPTION_STRING) michael@0: #define ST_WEB_OPTION_STRING(option_name, option_genre, default_value, option_help) michael@0: #endif michael@0: #if !defined(ST_CMD_OPTION_STRING_ARRAY) michael@0: #define ST_CMD_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help) michael@0: #endif michael@0: #if !defined(ST_WEB_OPTION_STRING_ARRAY) michael@0: #define ST_WEB_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help) michael@0: #endif michael@0: #if !defined(ST_CMD_OPTION_STRING_PTR_ARRAY) michael@0: #define ST_CMD_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help) michael@0: #endif michael@0: #if !defined(ST_WEB_OPTION_STRING_PTR_ARRAY) michael@0: #define ST_WEB_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help) michael@0: #endif michael@0: #if !defined(ST_CMD_OPTION_UINT32) michael@0: #define ST_CMD_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help) michael@0: #endif michael@0: #if !defined(ST_WEB_OPTION_UINT32) michael@0: #define ST_WEB_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help) michael@0: #endif michael@0: #if !defined(ST_CMD_OPTION_UINT64) michael@0: #define ST_CMD_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help) michael@0: #endif michael@0: #if !defined(ST_WEB_OPTION_UINT64) michael@0: #define ST_WEB_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help) michael@0: #endif michael@0: michael@0: /* michael@0: ** ALL macros expand to both CMD and WEB macros. michael@0: ** This basically means such options are accessible from both the command michael@0: ** line and from the web options. michael@0: */ michael@0: #define ST_ALL_OPTION_BOOL(option_name, option_genre, option_help) \ michael@0: ST_CMD_OPTION_BOOL(option_name, option_genre, option_help) \ michael@0: ST_WEB_OPTION_BOOL(option_name, option_genre, option_help) michael@0: #define ST_ALL_OPTION_STRING(option_name, option_genre, default_value, option_help) \ michael@0: ST_CMD_OPTION_STRING(option_name, option_genre, default_value, option_help) \ michael@0: ST_WEB_OPTION_STRING(option_name, option_genre, default_value, option_help) michael@0: #define ST_ALL_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help) \ michael@0: ST_CMD_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help) \ michael@0: ST_WEB_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help) michael@0: #define ST_ALL_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help) \ michael@0: ST_CMD_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help) \ michael@0: ST_WEB_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help) michael@0: #define ST_ALL_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help) \ michael@0: ST_CMD_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help) \ michael@0: ST_WEB_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help) michael@0: #define ST_ALL_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help) \ michael@0: ST_CMD_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help) \ michael@0: ST_WEB_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help) michael@0: michael@0: michael@0: michael@0: /**************************************************************************** michael@0: ** BEGIN, THE OPTIONS michael@0: ** michael@0: ** Order is somewhat relevant in that it will control 3 different things: michael@0: ** 1) The order the members will be in the options structure. michael@0: ** 2) The order the options are presented on the command line. michael@0: ** 3) The order the options are presented on the web options page. michael@0: */ michael@0: michael@0: ST_ALL_OPTION_STRING(CategoryName, michael@0: CategoryGenre, michael@0: ST_ROOT_CATEGORY_NAME, michael@0: "Specify a category for reports to focus upon.\n" michael@0: "See http://lxr.mozilla.org/mozilla/source/tools/trace-malloc/rules.txt\n") michael@0: michael@0: ST_ALL_OPTION_UINT32(OrderBy, michael@0: DataSortGenre, michael@0: ST_SIZE, /* for dp :-D */ michael@0: 1, michael@0: "Determine the sort order.\n" michael@0: "0 by weight (size * lifespan).\n" michael@0: "1 by size.\n" michael@0: "2 by lifespan.\n" michael@0: "3 by allocation count.\n" michael@0: "4 by performance cost.\n") michael@0: michael@0: ST_ALL_OPTION_STRING_ARRAY(RestrictText, michael@0: DataSetGenre, michael@0: ST_SUBSTRING_MATCH_MAX, michael@0: "Exclude allocations which do not have this text in their backtrace.\n" michael@0: "Multiple restrictions are treated as a logical AND operation.\n") michael@0: michael@0: ST_ALL_OPTION_UINT32(SizeMin, michael@0: DataSetGenre, michael@0: 0, michael@0: 1, michael@0: "Exclude allocations that are below this byte size.\n") michael@0: michael@0: ST_ALL_OPTION_UINT32(SizeMax, michael@0: DataSetGenre, michael@0: 0xFFFFFFFF, michael@0: 1, michael@0: "Exclude allocations that are above this byte size.\n") michael@0: michael@0: ST_ALL_OPTION_UINT32(LifetimeMin, michael@0: DataSetGenre, michael@0: ST_DEFAULT_LIFETIME_MIN, michael@0: ST_TIMEVAL_RESOLUTION, michael@0: "Allocations must live this number of seconds or be ignored.\n") michael@0: michael@0: ST_ALL_OPTION_UINT32(LifetimeMax, michael@0: DataSetGenre, michael@0: ST_TIMEVAL_MAX / ST_TIMEVAL_RESOLUTION, michael@0: ST_TIMEVAL_RESOLUTION, michael@0: "Allocations living longer than this number of seconds will be ignored.\n") michael@0: michael@0: ST_ALL_OPTION_UINT32(TimevalMin, michael@0: DataSetGenre, michael@0: 0, michael@0: ST_TIMEVAL_RESOLUTION, michael@0: "Allocations existing solely before this second will be ignored.\n" michael@0: "Live allocations at this second and after can be considered.\n") michael@0: michael@0: ST_ALL_OPTION_UINT32(TimevalMax, michael@0: DataSetGenre, michael@0: ST_TIMEVAL_MAX / ST_TIMEVAL_RESOLUTION, michael@0: ST_TIMEVAL_RESOLUTION, michael@0: "Allocations existing solely after this second will be ignored.\n" michael@0: "Live allocations at this second and before can be considered.\n") michael@0: michael@0: ST_ALL_OPTION_UINT32(AllocationTimevalMin, michael@0: DataSetGenre, michael@0: 0, michael@0: ST_TIMEVAL_RESOLUTION, michael@0: "Live and dead allocations created before this second will be ignored.\n") michael@0: michael@0: ST_ALL_OPTION_UINT32(AllocationTimevalMax, michael@0: DataSetGenre, michael@0: ST_TIMEVAL_MAX / ST_TIMEVAL_RESOLUTION, michael@0: ST_TIMEVAL_RESOLUTION, michael@0: "Live and dead allocations created after this second will be ignored.\n") michael@0: michael@0: ST_ALL_OPTION_UINT32(AlignBy, michael@0: DataSizeGenre, michael@0: ST_DEFAULT_ALIGNMENT_SIZE, michael@0: 1, michael@0: "All allocation sizes are made to be a multiple of this number.\n" michael@0: "Closer to actual heap conditions; set to 1 for true sizes.\n") michael@0: michael@0: ST_ALL_OPTION_UINT32(Overhead, michael@0: DataSizeGenre, michael@0: ST_DEFAULT_OVERHEAD_SIZE, michael@0: 1, michael@0: "After alignment, all allocations are made to increase by this number.\n" michael@0: "Closer to actual heap conditions; set to 0 for true sizes.\n") michael@0: michael@0: ST_ALL_OPTION_UINT32(ListItemMax, michael@0: UIGenre, michael@0: 500, michael@0: 1, michael@0: "Specifies the maximum number of list items to present in each list.\n") michael@0: michael@0: ST_ALL_OPTION_UINT64(WeightMin, michael@0: DataSetGenre, michael@0: 0, michael@0: 1, michael@0: "Exclude allocations that are below this weight (lifespan * size).\n") michael@0: michael@0: ST_ALL_OPTION_UINT64(WeightMax, michael@0: DataSetGenre, michael@0: (0xFFFFFFFFLL << 32) + 0xFFFFFFFFLL, michael@0: 1, michael@0: "Exclude allocations that are above this weight (lifespan * size).\n") michael@0: michael@0: ST_CMD_OPTION_STRING(FileName, michael@0: DataSetGenre, michael@0: "-", michael@0: "Specifies trace-malloc input file.\n" michael@0: "\"-\" indicates stdin will be used as input.\n") michael@0: michael@0: ST_CMD_OPTION_STRING(CategoryFile, michael@0: CategoryGenre, michael@0: "rules.txt", michael@0: "Specifies the category rules file.\n" michael@0: "This file contains rules about how to categorize allocations.\n") michael@0: michael@0: michael@0: ST_CMD_OPTION_UINT32(HttpdPort, michael@0: ServerGenre, michael@0: 1969, michael@0: 1, michael@0: "Specifies the default port the web server will listen on.\n") michael@0: michael@0: ST_CMD_OPTION_STRING(OutputDir, michael@0: BatchModeGenre, michael@0: ".", michael@0: "Specifies a directory to output batch mode requests.\n" michael@0: "The directory must exist and must not use a trailing slash.\n") michael@0: michael@0: ST_CMD_OPTION_STRING_PTR_ARRAY(BatchRequest, michael@0: BatchModeGenre, michael@0: "This implicitly turns on batch mode.\n" michael@0: "Save each requested file into the output dir, then exit.\n") michael@0: michael@0: ST_CMD_OPTION_UINT32(Contexts, michael@0: ServerGenre, michael@0: 1, michael@0: 1, michael@0: "How many configurations to cache at the cost of a lot of memory.\n" michael@0: "Dedicated servers can cache more client configurations for performance.\n") michael@0: michael@0: ST_CMD_OPTION_BOOL(Help, michael@0: UIGenre, michael@0: "Show command line help.\n" michael@0: "See http://www.mozilla.org/projects/footprint/spaceTrace.html\n") michael@0: michael@0: /* michael@0: ** END, THE OPTIONS michael@0: ****************************************************************************/ michael@0: michael@0: /* michael@0: ** Everything is undefined after the header is included. michael@0: ** This sets it up for multiple inclusion if so desired. michael@0: */ michael@0: #undef ST_ALL_OPTION_BOOL michael@0: #undef ST_CMD_OPTION_BOOL michael@0: #undef ST_WEB_OPTION_BOOL michael@0: #undef ST_ALL_OPTION_STRING michael@0: #undef ST_CMD_OPTION_STRING michael@0: #undef ST_WEB_OPTION_STRING michael@0: #undef ST_ALL_OPTION_STRING_ARRAY michael@0: #undef ST_CMD_OPTION_STRING_ARRAY michael@0: #undef ST_WEB_OPTION_STRING_ARRAY michael@0: #undef ST_ALL_OPTION_STRING_PTR_ARRAY michael@0: #undef ST_CMD_OPTION_STRING_PTR_ARRAY michael@0: #undef ST_WEB_OPTION_STRING_PTR_ARRAY michael@0: #undef ST_ALL_OPTION_UINT32 michael@0: #undef ST_CMD_OPTION_UINT32 michael@0: #undef ST_WEB_OPTION_UINT32 michael@0: #undef ST_ALL_OPTION_UINT64 michael@0: #undef ST_CMD_OPTION_UINT64 michael@0: #undef ST_WEB_OPTION_UINT64