| 1 |
.\" t |
| 2 |
.TH ERROR::SDT 7stap |
| 3 |
.SH NAME |
| 4 |
error::sdt \- <sys/sdt.h> marker failures |
| 5 |
|
| 6 |
.\" macros |
| 7 |
.de SAMPLE |
| 8 |
.br |
| 9 |
.RS |
| 10 |
.nf |
| 11 |
.nh |
| 12 |
.. |
| 13 |
.de ESAMPLE |
| 14 |
.hy |
| 15 |
.fi |
| 16 |
.RE |
| 17 |
.. |
| 18 |
|
| 19 |
|
| 20 |
.SH DESCRIPTION |
| 21 |
|
| 22 |
Systemtap's |
| 23 |
.BR <sys/sdt.h> |
| 24 |
probes are modeled after the dtrace USDT API, but are implemented |
| 25 |
differently. They leave a only a NOP instruction in the userspace |
| 26 |
program's text segment, and add an ELF note to the binary with |
| 27 |
metadata. This metadata describes the marker's name and parameters. |
| 28 |
This encoding is designed to be parseable by multiple tools (not just |
| 29 |
systemtap: GDB, the GNU Debugger, also contains support). These allow |
| 30 |
the tools to find parameters and their types, wherever they happen to |
| 31 |
reside, even without DWARF debuginfo. |
| 32 |
|
| 33 |
.PP |
| 34 |
|
| 35 |
The reason finding parameters is tricky is because the STAP_PROBE / |
| 36 |
DTRACE_PROBE markers store an assembly language expression for each |
| 37 |
operand, as a result of use of gcc inline-assembly directives. The |
| 38 |
compiler is given a broad gcc operand constraint string ("nor") for |
| 39 |
the operands, which usually works well. Usually, it does not force |
| 40 |
the compiler to load the parameters into or out of registers, which |
| 41 |
would slow down an instrumented program. However, some |
| 42 |
instrumentation sites with some parameters do not work well with the |
| 43 |
default "nor" constraint. |
| 44 |
|
| 45 |
.TP |
| 46 |
unresolveable at run-time |
| 47 |
GCC may emit strings that an assembler could resolve (from the |
| 48 |
context of compiling the original program), but a run-time tool |
| 49 |
cannot. For example, the operand string might refer to a label of a |
| 50 |
local symbol that is not emitted into the ELF object file at all, |
| 51 |
which leaves no trace for the run-time. Reference to such parameters |
| 52 |
from within systemtap can result in "SDT asm not understood" errors. |
| 53 |
|
| 54 |
.TP |
| 55 |
too complicated expression |
| 56 |
GCC might synthesize very complicated assembly addressing modes from |
| 57 |
complex C data types / pointer expressions. systemtap or gdb may not |
| 58 |
be able to parse some valid but complicated expressions. Reference to |
| 59 |
such parameters from within systemtap can result in "SDT asm not |
| 60 |
understood" errors. |
| 61 |
|
| 62 |
.TP |
| 63 |
overly restrictive constraint |
| 64 |
GCC might not be able to even compile the original program with the |
| 65 |
default "nor" constraint due to shortage of registers or other |
| 66 |
reasons. A compile-time gcc error such as "asm operand has impossible |
| 67 |
constraints" may result. |
| 68 |
|
| 69 |
.PP |
| 70 |
|
| 71 |
There are two general workarounds to this family of problems. |
| 72 |
|
| 73 |
.TP |
| 74 |
change the constraints |
| 75 |
While compiling the original instrumented program, set the |
| 76 |
.IR STAP_SDT_ARG_CONSTRAINT |
| 77 |
macro to different constraint strings. See the GCC manual about |
| 78 |
various options. For example, on many machine architectures, "r" forces |
| 79 |
operands into registers, and "g" leaves operands essentially unconstrained. |
| 80 |
|
| 81 |
.TP |
| 82 |
revert to debuginfo |
| 83 |
As long as the instrumented program compiles, it may be fine simply to |
| 84 |
keep using <sys/sdt.h> but eschew extraction of a few individual |
| 85 |
parameters. In the worst case, disable <sys/sdt.h> macros entirely to |
| 86 |
eschew the compiled-in instrumentation. If DWARF debuginfo was |
| 87 |
generated and preserved, a systemtap script could refer to the |
| 88 |
underlying source context variables instead of the positional |
| 89 |
STAP_PROBE parameters. |
| 90 |
|
| 91 |
.SH SEE ALSO |
| 92 |
.nh |
| 93 |
.nf |
| 94 |
.IR stap (1), |
| 95 |
.IR stapprobes (3stap), |
| 96 |
.IR error::dwarf (7stap), |
| 97 |
.IR http://gcc.gnu.org/onlinedocs/gcc/Constraints.html , |
| 98 |
.IR http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation , |
| 99 |
.IR error::reporting (7stap) |