From 374a36dbfb6d08ed8d77c31a88e198a861ffadf0 Mon Sep 17 00:00:00 2001 From: njn Date: Fri, 23 Nov 2007 01:41:32 +0000 Subject: Fixed up the log file mess throughout, including the docs. This killed --log-file-qualifier and --log-file-exactly. Updated NEWS some in preparation for 3.3.0. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@7202 a5019735-40e9-0310-863c-91ae7b9d1cf9 --- cachegrind/cg_annotate.in | 44 ++++--------- cachegrind/cg_main.c | 62 +++---------------- cachegrind/docs/cg-manual.xml | 140 ++++++++++++++++-------------------------- 3 files changed, 75 insertions(+), 171 deletions(-) (limited to 'cachegrind') diff --git a/cachegrind/cg_annotate.in b/cachegrind/cg_annotate.in index cb7e17e7a..31e95069b 100644 --- a/cachegrind/cg_annotate.in +++ b/cachegrind/cg_annotate.in @@ -142,13 +142,11 @@ my $version = "@VERSION@"; # Usage message. my $usage = < read profile data from cachegrind.out. - --cachegrind-out-file= read profile data from --show=A,B,C only show figures for events A,B,C [all] --sort=A,B,C sort columns by events A,B,C [event column order] --threshold=<0--100> percentage of counts (of primary sort event) we @@ -160,9 +158,6 @@ usage: cg_annotate [options] [source-files] -I --include= add to list of directories to search for source files - You must use either -- or --cachegrind-out-file exactly once - in order that cg_annotate knows what file to read profile data from. - cg_annotate is Copyright (C) 2002-2007 Nicholas Nethercote. and licensed under the GNU General Public License, version 2. Bug reports, feedback, admiration, abuse, etc, to: njn\@valgrind.org. @@ -241,25 +236,6 @@ sub process_cmd_line() $inc =~ s|/$||; # trim trailing '/' push(@include_dirs, "$inc/"); - # --cachegrind-out-file= - } elsif ($arg =~ /^--cachegrind-out-file=(.*)$/) { - if (not defined $input_file) { - $input_file = $1; - } else { - die("You may only specify one input file\n" . - "using the -- and --cachegrind-out-file options.\n"); - } - - # -- - } elsif ($arg =~ /^--(\d+)$/) { - my $pid = $1; - if (not defined $input_file) { - $input_file = "cachegrind.out.$pid"; - } else { - die("You may only specify one input file\n" . - "using the -- and --cachegrind-out-file options.\n"); - } - } else { # -h and --help fall under this case die($usage); } @@ -267,14 +243,20 @@ sub process_cmd_line() # Argument handling -- annotation file checking and selection. # Stick filenames into a hash for quick 'n easy lookup throughout. } else { - my $readable = 0; - foreach my $include_dir (@include_dirs) { - if (-r $include_dir . $arg) { - $readable = 1; + if (not defined $input_file) { + # First non-option argument is the output file. + $input_file = $arg; + } else { + # Subsequent non-option arguments are source files. + my $readable = 0; + foreach my $include_dir (@include_dirs) { + if (-r $include_dir . $arg) { + $readable = 1; + } } + $readable or die("File $arg not found in any of: @include_dirs\n"); + $user_ann_files{$arg} = 1; } - $readable or die("File $arg not found in any of: @include_dirs\n"); - $user_ann_files{$arg} = 1; } } diff --git a/cachegrind/cg_main.c b/cachegrind/cg_main.c index d8627fb86..9fae9de57 100644 --- a/cachegrind/cg_main.c +++ b/cachegrind/cg_main.c @@ -65,8 +65,9 @@ /*--- Options ---*/ /*------------------------------------------------------------*/ -static Bool clo_cache_sim = True; /* do cache simulation? */ -static Bool clo_branch_sim = False; /* do branch simulation? */ +static Bool clo_cache_sim = True; /* do cache simulation? */ +static Bool clo_branch_sim = False; /* do branch simulation? */ +static Char* clo_cachegrind_out_file = "cachegrind.out.%p"; /*------------------------------------------------------------*/ /*--- Types and Data Structures ---*/ @@ -1255,17 +1256,9 @@ static CacheCC Dw_total; static BranchCC Bc_total; static BranchCC Bi_total; -// The output file base name specified by the user using the -// --cachegrind-out-file switch. This is combined with the -// process ID and optional user-supplied qualifier (from -// --log-file-qualifier) to produce the name stored in -// cachegrind_out_file. -static Char* cachegrind_out_file_basename = "cachegrind.out"; - -// The final, completed name for the output file. +// The output file name. Controlled by --cachegrind-out-file. static Char* cachegrind_out_file = NULL; - static void fprint_CC_table_and_calc_totals(void) { Int i, fd; @@ -1691,7 +1684,7 @@ static Bool cg_process_cmd_line_option(Char* arg) else if (VG_CLO_STREQN(5, arg, "--L2=")) parse_cache_opt(&clo_L2_cache, &arg[5]); else if (VG_CLO_STREQN(22, arg, "--cachegrind-out-file=")) { - cachegrind_out_file_basename = &arg[22]; + clo_cachegrind_out_file = &arg[22]; } else VG_BOOL_CLO(arg, "--cache-sim", clo_cache_sim) else VG_BOOL_CLO(arg, "--branch-sim", clo_branch_sim) @@ -1709,8 +1702,7 @@ static void cg_print_usage(void) " --L2=,, set L2 cache manually\n" " --cache-sim=yes|no [yes] collect cache stats?\n" " --branch-sim=yes|no [no] collect branch prediction stats?\n" -" --cachegrind-out-file= write profile data to .\n" -" [cachegrind.out.]\n" +" --cachegrind-out-file= output file name [cachegrind.out.%%p]\n" ); } @@ -1725,8 +1717,6 @@ static void cg_print_debug_usage(void) /*--- Setup ---*/ /*--------------------------------------------------------------------*/ -static Char base_dir[VKI_PATH_MAX]; - static void cg_post_clo_init(void); /* just below */ static void cg_pre_clo_init(void) @@ -1751,9 +1741,7 @@ static void cg_pre_clo_init(void) static void cg_post_clo_init(void) { - HChar* qual = NULL; cache_t I1c, D1c, L2c; - Int filename_szB; /* Can't disable both cache and branch profiling */ if ((!clo_cache_sim) && (!clo_branch_sim)) { @@ -1764,41 +1752,9 @@ static void cg_post_clo_init(void) VG_(exit)(2); } - /* Get working directory */ - tl_assert( VG_(get_startup_wd)(base_dir, VKI_PATH_MAX) ); - - /* Do we have a --log-file-qualifier= to consider? */ - if (VG_(clo_log_file_qualifier)) { - qual = VG_(getenv)(VG_(clo_log_file_qualifier)); - } - - /* Block is big enough for - dir name ++ cachegrind_out_file_basename - ++ "." - ++ the log file qualifier, if in use */ - filename_szB - = VG_(strlen)(base_dir) - + 1 /* "/" */ - + VG_(strlen)(cachegrind_out_file_basename) - + 11 /* "." , assuming sizeof(pid) <= 4 */ - + (qual ? (10 + VG_(strlen)(qual)) : 0) - + 1; /* to guarantee checkable zero at the end */ - - tl_assert(filename_szB > 0); - cachegrind_out_file - = VG_(calloc)( sizeof(Char), filename_szB ); - - if (qual) { - VG_(sprintf)(cachegrind_out_file, "%s/%s.%d.lfq.%s", - base_dir, cachegrind_out_file_basename, - VG_(getpid)(), qual); - } else { - VG_(sprintf)(cachegrind_out_file, "%s/%s.%d", - base_dir, cachegrind_out_file_basename, - VG_(getpid)()); - } - - tl_assert( cachegrind_out_file[filename_szB-1] == 0 ); + // Setup output filename. + cachegrind_out_file = + VG_(expand_file_name)("--cachegrind-out-file", clo_cachegrind_out_file); CC_table = VG_(OSetGen_Create)(offsetof(LineCC, loc), diff --git a/cachegrind/docs/cg-manual.xml b/cachegrind/docs/cg-manual.xml index 59b70e1d8..30857fa9f 100644 --- a/cachegrind/docs/cg-manual.xml +++ b/cachegrind/docs/cg-manual.xml @@ -78,9 +78,9 @@ be normally run. command line invocation. When the program finishes, Cachegrind will print summary cache statistics. It also collects line-by-line information in a file - cachegrind.out.pid, where - pid is the program's process - id. + cachegrind.out.<pid>, where + <pid> is the program's process + ID. Branch prediction statistics are not collected by default. To do so, add the flag @@ -95,7 +95,7 @@ be normally run. Generate a function-by-function summary, and possibly annotate source files, using the supplied - cg_annotate program. Source + cg_annotate program. Source files to annotate can be specified manually, or manually on the command line, or "interesting" source files can be annotated automatically with the @@ -111,10 +111,9 @@ be normally run. As an optional intermediate step, you can use the supplied -cg_merge program to sum together the +cg_merge program to sum together the outputs of multiple Cachegrind runs, into a single file which you then -use as the input for -cg_annotate. +use as the input for cg_annotate. These steps are described in detail in the following sections. @@ -336,46 +335,38 @@ follow that. As well as printing summary information, Cachegrind also writes line-by-line cache profiling information to a user-specified file. By default this file is named -cachegrind.out.pid. This file +cachegrind.out.<pid>. This file is human-readable, but is intended to be interpreted by the accompanying -program cg_annotate, described -in the next section. +program cg_annotate, described in the next section. Things to note about the -cachegrind.out.pid +cachegrind.out.<pid> file: It is written every time Cachegrind is run, and will overwrite any existing - cachegrind.out.pid + cachegrind.out.<pid> in the current directory (but that won't happen very often because it takes some time for process ids to be recycled). - - To use a basename other than the default + + + To use an output file name other than the default cachegrind.out, use the --cachegrind-out-file switch. - - To add further qualifiers to the output filename you can use - the core's --log-file-qualifier - flag. This extends the file name further with the text - .lfq.followed by the - contents of the environment variable specified by - --log-file-qualifier. - - It can be huge: ls -l + It can be big: ls -l generates a file of about 350KB. Browsing a few files and web pages with a Konqueror built with full debugging information generates a file of around 15 MB. -The .pid suffix +The default .<pid> suffix on the output file name serves two purposes. Firstly, it means you don't have to rename old log files that you don't want to overwrite. Secondly, and more importantly, it allows correct profiling with the @@ -439,13 +430,18 @@ configuration, or failing that, via defaults). - + Write the profile data to - basename.pid - rather than to the default output file, - cachegrind.out.pid. + file rather than to the default + output file, + cachegrind.out.<pid>. The + and format specifiers + can be used to embed the process ID and/or the contents of an + environment variable in the name, as is the case for the core + option . See here for details. @@ -485,16 +481,12 @@ configuration, or failing that, via defaults). Annotating C/C++ programs -Before using cg_annotate, +Before using cg_annotate, it is worth widening your window to be at least 120-characters wide if possible, as the output lines can be quite long. -To get a function-by-function summary, run -cg_annotate --pid in a directory -containing a cachegrind.out.pid file. The ---pid is required so that -cg_annotate knows which log file to use -when several are present. +To get a function-by-function summary, run cg_annotate +<filename> on a Cachegrind output file. The output looks like this: @@ -643,7 +635,7 @@ Ir I1mr I2mr Dr D1mr D2mr Dw D1mw D2mw file:function - Threshold: cg_annotate + Threshold: cg_annotate by default omits functions that cause very low counts to avoid drowning you in information. In this case, cg_annotate shows summaries the functions that account for @@ -696,12 +688,12 @@ and from libraries (eg. getc.c) There are two ways to annotate source files -- by choosing them manually, or with the --auto=yes option. To do it -manually, just specify the filenames as arguments to -cg_annotate. For example, the -output from running cg_annotate concord.c -for our example produces the same output as above followed by an -annotated version of concord.c, a section of -which looks like: +manually, just specify the filenames as additional arguments to +cg_annotate. For example, the +output from running cg_annotate <filename> +concord.c for our example produces the same output as above +followed by an annotated version of concord.c, a +section of which looks like: --context option. To get automatic annotation, run -cg_annotate --auto=yes. +cg_annotate <filename> --auto=yes. cg_annotate will automatically annotate every source file it can find that is mentioned in the function-by-function summary. Therefore, the files chosen for auto-annotation are affected by @@ -798,7 +790,7 @@ for source files if the filenames found from the debugging information aren't specific enough. Beware that cg_annotate can take some time to digest large -cachegrind.out.pid files, +cachegrind.out.<pid> files, e.g. 30 seconds or more. Also beware that auto-annotation can produce a lot of output if your program is large! @@ -806,10 +798,10 @@ produce a lot of output if your program is large! -Annotating assembler programs +Annotating assembly code programs -Valgrind can annotate assembler programs too, or annotate -the assembler generated for your C program. Sometimes this is +Valgrind can annotate assembly code programs too, or annotate +the assembly code generated for your C program. Sometimes this is useful for understanding what is really happening when an interesting line of C code is translated into multiple instructions. @@ -832,34 +824,10 @@ way as for C/C++ programs. -<computeroutput>cg_annotate</computeroutput> options +cg_annotate options - - --pid - Indicates that profile data should be read from - the file - cachegrind.out.pid. - read. - Note that you must specify either - --pid - or --cachegrind-out-file=filename - exactly once. - - - - - --cachegrind-out-file=filename - Indicates that profile data - should be read from filename. - Note that you must specify either - --pid - or --cachegrind-out-file=filename - exactly once. - - - -h, --help -v, --version @@ -869,7 +837,7 @@ way as for C/C++ programs. --sort=A,B,C [default: order in - cachegrind.out.pid] + cachegrind.out.<pid>] Specifies the events upon which the sorting of the function-by-function entries will be based. Useful if you want to concentrate on eg. I cache misses @@ -883,10 +851,10 @@ way as for C/C++ programs. --show=A,B,C [default: all, using order in - cachegrind.out.pid] + cachegrind.out.<pid>] Specifies which events to show (and the column order). Default is to use all present in the - cachegrind.out.pid file (and + cachegrind.out.<pid> file (and use the order in the file). @@ -941,15 +909,14 @@ way as for C/C++ programs. Warnings There are a couple of situations in which -cg_annotate issues -warnings. +cg_annotate issues warnings. If a source file is more recent than the - cachegrind.out.pid file. + cachegrind.out.<pid> file. This is because the information in - cachegrind.out.pid is only + cachegrind.out.<pid> is only recorded with line numbers, so if the line numbers change at all in the source (eg. lines added, deleted, swapped), any annotations will be incorrect. @@ -958,7 +925,7 @@ warnings. If information is recorded about line numbers past the end of a file. This can be caused by the above problem, ie. shortening the source file while using an old - cachegrind.out.pid file. If + cachegrind.out.<pid> file. If this happens, the figures for the bogus lines are printed anyway (clearly marked as bogus) in case they are important. @@ -1167,22 +1134,21 @@ useful. -Merging profiles with <computeroutput>cg_merge</computeroutput> +Merging profiles with cg_merge -cg_merge is a simple program which +cg_merge is a simple program which reads multiple profile files, as created by cachegrind, merges them together, and writes the results into another file in the same format. You can then examine the merged results using -cg_annotate ---cachegrind-out-file=outputfile, as +cg_annotate <filename>, as described above. The merging functionality might be useful if you want to aggregate costs over multiple runs of the same program, or from a single parallel run with multiple instances of the same program. -cg_merge is invoked as follows: +cg_merge is invoked as follows: -cg_merge does not attempt to check +cg_merge does not attempt to check that the input files come from runs of the same executable. It will happily merge together profile files from completely unrelated programs. It does however check that the @@ -1215,7 +1181,7 @@ write misses. A number of other syntax and sanity checks are done whilst reading the -inputs. cg_merge will stop and +inputs. cg_merge will stop and attempt to print a helpful error message if any of the input files fail these checks. -- cgit v1.2.3