PR27934: give fuller diagnosis for pass-5 probe-registration errors

While we cannot solve or prevent runtime probe registration errors, we
can help users understand them.  Add a new warning::pass5 man page,
and point registration error messages at it.

diff --git a/man/error::pass5.7stap b/man/error::pass5.7stap
index 7cd015052e11cbf7a0d29eb3ef8a711a08e8fa0a..04bb1453b3ecce4875ba972ee9a1cf6836d6d32c 100644 (file)
--- a/man/error::pass5.7stap
+++ b/man/error::pass5.7stap
@@ -117,3 +117,4 @@ can help pinpoint the problem.
 .IR http://sourceware.org/systemtap/wiki/TipExhaustedResourceErrors ,
 .IR error::fault (7stap),
 .IR error::reporting (7stap)
+.IR warning::pass5 (7stap)

diff --git a/man/warning::pass5.7stap b/man/warning::pass5.7stap
new file mode 100644 (file)
index 0000000..4ff4f97
--- /dev/null
+++ b/man/warning::pass5.7stap
@@ -0,0 +1,59 @@
+.\" t    -*- nroff -*-
+
+.TH ERROR::PASS5 7stap 
+.SH NAME
+warning::pass5 \- systemtap pass-5 warnings
+
+.\" macros
+.de SAMPLE
+
+.nr oldin \\n(.i
+.br
+.RS
+.nf
+.nh
+..
+.de ESAMPLE
+.hy
+.fi
+.RE
+.in \\n[oldin]u
+
+..
+
+.SH DESCRIPTION
+Warnings that occur during pass 5 (execution) can have a variety of causes.
+
+
+.TP
+probe insertion errors
+With any of the systemtap runtimes, it may be possible that the
+backends are unable to insert probe points requested by the systemtap
+script.  For example, you may see errors such as
+.SAMPLE
+WARNING: probe [...] registration error (rc -524)
+.ESAMPLE
+(524 is a kernel error code for ENOTSUPP).  These situations are out
+of systemtap's control, and result in some probes not receiving any
+hits.  This may be caused by temporary resource constraints or
+permanent problems.  One common permanent problem is such a probe
+point being placed at instructions that the runtime (kernel kprobes,
+uprobes or dyninst) cannot decode or intercept.  A possible workaround
+is to move the probe points slightly in the script, so as to target a
+nearby statement, or a caller, or a callee.  See also
+.IR error::dwarf (7stap).
+
+.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
+.nh
+.nf
+.IR stap (1),
+.IR http://sourceware.org/systemtap/wiki/TipExhaustedResourceErrors ,
+.IR error::pass5 (7stap),
+.IR error::reporting (7stap)
+.IR error::dwarf (7stap)

diff --git a/runtime/linux/kprobes.c b/runtime/linux/kprobes.c
index df47b080d6c2e1744f8db638f2fba7a2e1df5ebd..508e4172f93d21b6c00a12d6a744ffbea05ab8b1 100644 (file)
--- a/runtime/linux/kprobes.c
+++ b/runtime/linux/kprobes.c
@@ -772,10 +772,10 @@ stapkp_init(struct stap_kprobe_probe *probes,
          && ((skp->module == NULL) || skp->module[0] == '\0'
              || strcmp(skp->module, "kernel") == 0)) {
         if (skp->symbol_name)
-           _stp_warn("probe %s (%s+%u) registration error (rc %d)",
+           _stp_warn("probe %s (%s+%u) registration error [man warning::pass5] (rc %d)",
                      skp->probe->pp, skp->symbol_name, skp->offset, rc);
         else
-           _stp_warn("probe %s (address 0x%lx) registration error (rc %d)",
+           _stp_warn("probe %s (address 0x%lx) registration error [man warning::pass5] (rc %d)",
                      skp->probe->pp, stapkp_relocate_addr(skp), rc);
       }
    }

diff --git a/runtime/linux/uprobes-inode.c b/runtime/linux/uprobes-inode.c
index 757da30d25e9c407fc9f486ddd2b2e56968092a6..411d2188442d68f31d045525b834daed048ba76a 100644 (file)
--- a/runtime/linux/uprobes-inode.c
+++ b/runtime/linux/uprobes-inode.c
@@ -267,7 +267,7 @@ stapiu_register (struct stapiu_instance* inst, struct stapiu_consumer* c)
 
   if (ret)
     _stp_warn("probe %s at inode-offset %lu:%p "
-             "registration error (rc %d)",
+             "registration error [man warning::pass5] (rc %d)",
              c->probe->pp,
              (unsigned long) inst->inode->i_ino,
              (void*) (uintptr_t) c->offset,

diff --git a/tapsets.cxx b/tapsets.cxx
index 20e0cb68f3b2110f9cf6f0de1beda2e29eadc200..7d650e15fe443e80028d50881a30c7f673f9bb05 100644 (file)
--- a/tapsets.cxx
+++ b/tapsets.cxx
@@ -10839,7 +10839,7 @@ hwbkpt_derived_probe_group::emit_module_init (systemtap_session& s)
   s.op->newline() << "stap_hwbkpt_ret_array[i] = 0;";
   s.op->newline(-1) << "}";
   s.op->newline() << "if (rc) {";
-  s.op->newline(1) << "_stp_warn(\"Hwbkpt probe %s: registration error %d, addr %p, name %s\", probe_point, rc, addr, hwbkpt_symbol_name);";
+  s.op->newline(1) << "_stp_warn(\"Hwbkpt probe %s: registration error [man warning::pass5] %d, addr %p, name %s\", probe_point, rc, addr, hwbkpt_symbol_name);";
   s.op->newline() << "skp->registered_p = 0;";
   s.op->newline(-1) << "}";
   s.op->newline() << " else skp->registered_p = 1;";

diff --git a/translate.cxx b/translate.cxx
index d85483b92a3d3a104fee007fa54baa28e30468bc..59fa2e4a03d1cfbacb88d411c6dd6f310cb4643e 100644 (file)
--- a/translate.cxx
+++ b/translate.cxx
@@ -2062,7 +2062,7 @@ c_unparser::emit_module_init ()
       // If a probe types's emit_module_init() wants to handle error
       // messages itself, it should set probe_point to NULL, 
       o->newline(1) << "if (probe_point)";
-      o->newline(1) << "_stp_error (\"probe %s registration error (rc %d)\", probe_point, rc);";
+      o->newline(1) << "_stp_error (\"probe %s registration error [man warning::pass5] (rc %d)\", probe_point, rc);";
       o->indent(-1);
       // NB: we need to be in the error state so timers can shutdown cleanly,
       // and so end probes don't run.  OTOH, error probes can run.