From 1f35f4dbc67863b0f318ec1a6b05092dbc2d7205 Mon Sep 17 00:00:00 2001 From: "Frank Ch. Eigler" Date: Mon, 28 Jan 2013 17:21:10 -0500 Subject: [PATCH] PR14929: add a basic error:: man page for each pass --- main.cxx | 27 ++++---------- man/error::pass1.7stap | 55 +++++++++++++++++++++++++++++ man/error::pass2.7stap | 56 +++++++++++++++++++++++++++++ man/error::pass3.7stap | 26 ++++++++++++++ man/error::pass4.7stap | 12 ++++--- man/error::pass5.7stap | 68 ++++++++++++++++++++++++++++++++++++ man/warning::debuginfo.7stap | 9 ++++- 7 files changed, 226 insertions(+), 27 deletions(-) create mode 100644 man/error::pass1.7stap create mode 100644 man/error::pass2.7stap create mode 100644 man/error::pass3.7stap create mode 100644 man/error::pass5.7stap diff --git a/main.cxx b/main.cxx index efc67ddf0..0c8f17376 100644 --- a/main.cxx +++ b/main.cxx @@ -1,5 +1,5 @@ // systemtap translator/driver -// Copyright (C) 2005-2011 Red Hat Inc. +// Copyright (C) 2005-2013 Red Hat Inc. // Copyright (C) 2005 IBM Corp. // Copyright (C) 2006 Intel Corporation. // @@ -689,10 +689,7 @@ passes_0_4 (systemtap_session &s) } if (rc && !s.listing_mode) - cerr << _("Pass 1: parse failed. Try again with another '--vp 1' option.") << endl; - //cerr << "Pass 1: parse failed. " - // << "Try again with another '--vp 1' option." - // << endl; + cerr << _("Pass 1: parse failed. [man error::pass1]") << endl; PROBE1(stap, pass1__end, &s); @@ -727,13 +724,7 @@ passes_0_4 (systemtap_session &s) << endl; if (rc && !s.listing_mode && !s.try_server ()) - cerr << _("Pass 2: analysis failed. Try again with another '--vp 01' option.") << endl; - //cerr << "Pass 2: analysis failed. " - // << "Try again with another '--vp 01' option." - // << endl; - - /* Print out list of missing files. XXX should be "if (rc)" ? */ - missing_rpm_list_print(s,"-debuginfo"); + cerr << _("Pass 2: analysis failed. [man error::pass2]") << endl; PROBE1(stap, pass2__end, &s); @@ -805,10 +796,7 @@ passes_0_4 (systemtap_session &s) << endl; if (rc && ! s.try_server ()) - cerr << _("Pass 3: translation failed. Try again with another '--vp 001' option.") << endl; - //cerr << "Pass 3: translation failed. " - // << "Try again with another '--vp 001' option." - // << endl; + cerr << _("Pass 3: translation failed. [man error::pass3]") << endl; PROBE1(stap, pass3__end, &s); @@ -843,7 +831,7 @@ passes_0_4 (systemtap_session &s) << endl; if (rc && ! s.try_server ()) - cerr << _("Pass 4: compilation failed. [man error::pass4]") << endl; + cerr << _("Pass 4: compilation failed. [man error::pass4]") << endl; else { @@ -897,10 +885,7 @@ pass_5 (systemtap_session &s, vector targets) << endl; if (rc) - cerr << _("Pass 5: run failed. Try again with another '--vp 00001' option.") << endl; - //cerr << "Pass 5: run failed. " - // << "Try again with another '--vp 00001' option." - // << endl; + cerr << _("Pass 5: run failed. [man error::pass5]") << endl; else // Interrupting pass-5 to quit is normal, so we want an EXIT_SUCCESS below. pending_interrupts = 0; diff --git a/man/error::pass1.7stap b/man/error::pass1.7stap new file mode 100644 index 000000000..596dc2a09 --- /dev/null +++ b/man/error::pass1.7stap @@ -0,0 +1,55 @@ +.\" t +.TH ERROR::PASS1 7stap +.SH NAME +error::pass1 \- systemtap pass-1 errors + +.SH DESCRIPTION Errors that occur during pass 1 (parsing) usually mean +a basic syntax error of some sort occurred in the systemtap script. +There are several classes of problems possible: + +.TP +plain syntax error +The systemtap script parser detects a large variety of errors, such as +missing operands, bad punctuation. It tries to list what kinds of tokens +it was expecting to see, and will show the region of the source code with +the problem. Please review the +.IR stap (1) +man page and/or the tutorial, to correct the script's syntax. + +.TP +grammar ambiguities +There is at least one known ambiguity in the systemtap grammar. It relates +to the optionality of +.IR ; +(semicolon) separators between statements, and the +.IR ++ " and " -- +increment/decrement operators. If the parser indicates an error, consider +adding some explicit +.IR ; +separators between nearby statements and try again. + +.TP +missing command line arguments +A systemtap script that uses the +.IR $N " and " @N +constructs for substituting in command-line options may fail if not +enough options were given on the stap command line. + +.TP +compatibility changes +Some versions of systemtap have changed the language incompatibly, +for example by adding the try/catch keywords for exception handling. +In such cases, rerun systemtap with the +.IR \-\-compatibility=VERSION +option, substituting the last systemtap version where your script +was known to work. You may also check the release-history NEWS file +for compatibility changes. + +.SH GATHERING MORE INFORMATION +Increasing the verbosity of pass-1 with an option such as +.IR "--vp 1" +can help pinpoint the problem. + +.SH SEE ALSO +.IR stap (1), +.IR error::reporting (7stap) diff --git a/man/error::pass2.7stap b/man/error::pass2.7stap new file mode 100644 index 000000000..e881bbe08 --- /dev/null +++ b/man/error::pass2.7stap @@ -0,0 +1,56 @@ +.\" t +.TH ERROR::PASS2 7stap +.SH NAME +error::pass2 \- systemtap pass-2 errors + +.SH DESCRIPTION +Errors that occur during pass 2 (elaboration) can have a variety of causes. +Common types include: + +.TP +unavailable probe points +Some types of probe points are only available on certain system versions, +architectures, and configurations. For example, user-space +.IR "(" process. ")" +probes may require utrace or uprobes capability in the kernel for this +architecture. Debugging or symbol data may be absent for +.IR .function " or " .statement +probes. Use the +.IR "stap \-L" +option to list available probe points. Use the +.IR ! " or " ? +probe point suffixes to denote optional / preferred-alternatives, to let +the working parts of a script continue. Check for availability of debuginfo. + +.TP +typos +There might be a spelling error in the probe point name ("sycsall" vs. +"syscall"). Wildcard probes may not find a match at all in the +tapsets. Recheck the names. + +.TP +unavailable context variables +Systemtap scripts often wish to refer to variables from the context of the +probed programs using +.IR $variable +notation. These variables may not always be available, depending on versions +of the compiler, debugging/optimization flags used, architecture, etc. Use +the +.IR @defined() +expression to test for the resolvability of a context variable expression. +Consider using the +.IR "stap --skip-badvars" +option to silently replace misbehaving context variable expressions with zero. + +.SH GATHERING MORE INFORMATION +Increasing the verbosity of pass-2 with an option such as +.IR "--vp 02" +can help pinpoint the problem. + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap), +.IR probe::* (3stap), +.IR error::dwarf (7stap), +.IR warning::debuginfo (7stap), +.IR error::reporting (7stap) diff --git a/man/error::pass3.7stap b/man/error::pass3.7stap new file mode 100644 index 000000000..3ed576d8b --- /dev/null +++ b/man/error::pass3.7stap @@ -0,0 +1,26 @@ +.\" t +.TH ERROR::PASS3 7stap +.SH NAME +error::pass3 \- systemtap pass-3 errors + +.SH DESCRIPTION +Errors during pass 3 (translation) occur only rarely. + +.TP +unsupported code generation +Some script language constructs are not available in every +probe point. For example, the +.IR @perf() +counter-reading function may only be used in +.IR process.* +probes. + +.SH GATHERING MORE INFORMATION +Increasing the verbosity of pass-3 with an option such as +.IR "--vp 002" +may help pinpoint the problem. + +.SH SEE ALSO +.IR stap (1), +.IR stapprobes (3stap) +.IR error::reporting (7stap) diff --git a/man/error::pass4.7stap b/man/error::pass4.7stap index c0acc8118..23d191029 100644 --- a/man/error::pass4.7stap +++ b/man/error::pass4.7stap @@ -18,16 +18,18 @@ include relevant fixes, so try getting or making an updated build. If the issue persists, report the problem to the systemtap developers. .TP -buggy embedded-C code in user script +buggy embedded-C code Embedded-C code in your own guru-mode script cannot be checked by systemtap, and is passed through verbatim to the compiler. Errors in such snippets of code may be found during the pass-4 compiler invocation, though may be hard -to identify by the compiler errors. It may be necessary to run systemtap -with +to identify by the compiler errors. + +.SH GATHERING MORE INFORMATION +It may be necessary to run systemtap with .IR -k " or " -p3 -to examine the generated C code. Increasing the verbosity of pass-4 +to examine the generated C code. Increasing the verbosity of pass-4 with an option such as -.IR --vp 0001 +.IR "--vp 0001" can also help pinpoint the problem. .SH SEE ALSO diff --git a/man/error::pass5.7stap b/man/error::pass5.7stap new file mode 100644 index 000000000..848ec59ee --- /dev/null +++ b/man/error::pass5.7stap @@ -0,0 +1,68 @@ +.\" t +.TH ERROR::PASS5 7stap +.SH NAME +error::pass5 \- systemtap pass-5 errors + +.SH DESCRIPTION +Errors that occur during pass 5 (execution) can have a variety of causes. + +.TP +exceptional events during script execution +The systemtap translator and runtime include numerous error checks +that aim to protect the systems and the users from mistakes or +transient conditions. The script may deliberately call the +.IR error() +tapset function to signal a problem. Some memory needed for +accessing +.IR $context +variables may be temporarily unavailable. Consider using the +.IR try / catch +construct to wrap script fragments in exception-handling code. +Consider using the +.IR "stap --suppress-handler-errors" +or +.IR "stap --skip-badvars" +option. + +.TP +resource exhaustion +One of several types of space or time resource limits may be +exceeded by the script, including system overload, too many tuples +to be stored in an array, etc. Some of the error messages identify +the constraint by macro name, which may be individually raised. +Consider using the +.IR "stap --suppress-handler-errors" +option. Extend or disable resource limits using the +.IR "stap -DLIMIT=NNNN" +option. +.\" the systemtap/wiki/TipExhaustedResourceErrors should be transcribed here + +.TP +remote execution server problems +If you use the +.IR "stap --remote" +option to direct a systemtap script to be executed somewhere else, +ensure that an SSH connection may be made to the remote host, and +that it has the current systemtap runtime installed & available. + +.TP +installation/permission problems +It is possible that your installation of systemtap was not correctly +installed. For example, the +.IR /usr/bin/staprun +program may lack the necessary setuid permissions, or environment +variables may interfere with locating +.IR /usr/libexec/.../stapio "." + + +.SH GATHERING MORE INFORMATION +Increasing the verbosity of pass-5 +with an option such as +.IR "--vp 00001" +can help pinpoint the problem. + +.SH SEE ALSO +.IR stap (1), +.IR http://sourceware.org/systemtap/wiki/TipExhaustedResourceErrors , +.IR error::fault (7stap), +.IR error::reporting (7stap) diff --git a/man/warning::debuginfo.7stap b/man/warning::debuginfo.7stap index 1660eec23..7ce8c0eec 100644 --- a/man/warning::debuginfo.7stap +++ b/man/warning::debuginfo.7stap @@ -45,11 +45,18 @@ flag. The .IR stap-prep script included with systemtap may be able to download the -appropriate kernel debuginfo. +appropriate kernel debuginfo. Another possibility is to install and +use a +.IR stap\-server +remote-compilation instance on a machine on your network, where +debuginfo and compilation resources can be centralized. Try the +.IR "stap --use-server" +option, in case such a server is already running. .SH SEE ALSO .IR stap (1), .IR stappaths (7), +.IR stap-server (8), .IR strip (1), .IR error::reporting (7stap) .IR error::contextvars (7stap) -- 2.43.5