1ERROR::SDT(7stap)                                            ERROR::SDT(7stap)
2
3
4

NAME

6       error::sdt - <sys/sdt.h> marker failures
7
8
9
10

DESCRIPTION

12       Systemtap's  <sys/sdt.h>  probes are modeled after the dtrace USDT API,
13       but are implemented differently.  They leave a only a  NOP  instruction
14       in  the  userspace  program's  text segment, and add an ELF note to the
15       binary with metadata.  This metadata describes the  marker's  name  and
16       parameters.   This  encoding  is  designed  to be parseable by multiple
17       tools (not just systemtap: GDB, the GNU Debugger,  also  contains  sup‐
18       port).  These allow the tools to find parameters and their types, wher‐
19       ever they happen to reside, even without DWARF debuginfo.
20
21
22       The reason finding parameters is tricky is  because  the  STAP_PROBE  /
23       DTRACE_PROBE markers store an assembly language expression for each op‐
24       erand, as a result of use of gcc inline-assembly directives.  The  com‐
25       piler  is  given  a broad gcc operand constraint string ("nor") for the
26       operands, which usually works well.  Usually, it  does  not  force  the
27       compiler  to  load the parameters into or out of registers, which would
28       slow down an instrumented program.  However, some instrumentation sites
29       with  some  parameters  do  not  work  well with the default "nor" con‐
30       straint.
31
32
33       unresolveable at run-time
34              GCC may emit strings that an assembler could resolve  (from  the
35              context  of compiling the original program), but a run-time tool
36              cannot.  For example, the operand string might refer to a  label
37              of  a  local symbol that is not emitted into the ELF object file
38              at all, which leaves no trace for the  run-time.   Reference  to
39              such parameters from within systemtap can result in "SDT asm not
40              understood" errors.
41
42
43       too complicated expression
44              GCC might synthesize very complicated assembly addressing  modes
45              from  complex  C data types / pointer expressions.  systemtap or
46              gdb may not be able to parse some valid but complicated  expres‐
47              sions.   Reference  to such parameters from within systemtap can
48              result in "SDT asm not understood" errors.
49
50
51       overly restrictive constraint
52              GCC might not be able to even compile the original program  with
53              the  default  "nor"  constraint  due to shortage of registers or
54              other reasons.  A compile-time gcc error such  as  "asm  operand
55              has impossible constraints" may result.
56
57
58       There are two general workarounds to this family of problems.
59
60
61       change the constraints
62              While  compiling  the  original  instrumented  program,  set the
63              STAP_SDT_ARG_CONSTRAINT macro to different  constraint  strings.
64              See  the GCC manual about various options.  For example, on many
65              machine architectures, "r" forces operands into  registers,  and
66              "g" leaves operands essentially unconstrained.
67
68
69       revert to debuginfo
70              As  long  as  the  instrumented program compiles, it may be fine
71              simply to keep using <sys/sdt.h> but eschew extraction of a  few
72              individual  parameters.   In the worst case, disable <sys/sdt.h>
73              macros entirely to eschew the compiled-in  instrumentation.   If
74              DWARF  debuginfo was generated and preserved, a systemtap script
75              could refer to the underlying source context  variables  instead
76              of the positional STAP_PROBE parameters.
77
78

SEE ALSO

80       stap(1),
81       stapprobes(3stap),
82       error::dwarf(7stap),
83       http://gcc.gnu.org/onlinedocs/gcc/Constraints.html,
84       http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation,
85       error::reporting(7stap)
86
87
88
89                                                             ERROR::SDT(7stap)
Impressum