NAME

       error::sdt - <sys/sdt.h> marker failures

DESCRIPTION

       Systemtap's  <sys/sdt.h> probes are modeled after the dtrace USDT API, but are implemented
       differently.  They leave a only a NOP instruction in the userspace program's text segment,
       and  add  an  ELF  note to the binary with metadata.  This metadata describes the marker's
       name and parameters.  This encoding is designed to be parseable  by  multiple  tools  (not
       just  systemtap:  GDB, the GNU Debugger, also contains support).  These allow the tools to
       find parameters and their types, wherever  they  happen  to  reside,  even  without  DWARF
       debuginfo.

       The  reason  finding parameters is tricky is because the STAP_PROBE / DTRACE_PROBE markers
       store an assembly language expression for each operand, as a result of use of gcc  inline-
       assembly  directives.  The compiler is given a broad gcc operand constraint string ("nor")
       for the operands, which usually works well.  Usually, it does not force  the  compiler  to
       load  the  parameters  into  or  out  of  registers, which would slow down an instrumented
       program.  However, some instrumentation sites with some parameters do not work  well  with
       the default "nor" constraint.

       unresolveable at run-time
              GCC may emit strings that an assembler could resolve (from the context of compiling
              the original program), but a run-time tool cannot.  For example, the operand string
              might  refer  to  a label of a local symbol that is not emitted into the ELF object
              file at all, which leaves no trace for the run-time.  Reference to such  parameters
              from within systemtap can result in "SDT asm not understood" errors.

       too complicated expression
              GCC might synthesize very complicated assembly addressing modes from complex C data
              types / pointer expressions.  systemtap or gdb may not be able to parse some  valid
              but  complicated  expressions.   Reference to such parameters from within systemtap
              can result in "SDT asm not understood" errors.

       overly restrictive constraint
              GCC might not be able to even compile the original program with the  default  "nor"
              constraint due to shortage of registers or other reasons.  A compile-time gcc error
              such as "asm operand has impossible constraints" may result.

       There are two general workarounds to this family of problems.

       change the constraints
              While compiling the original instrumented program, set the  STAP_SDT_ARG_CONSTRAINT
              macro  to  different constraint strings.  See the GCC manual about various options.
              For example, on many machine architectures, "r" forces operands into registers, and
              "g" leaves operands essentially unconstrained.

       revert to debuginfo
              As  long  as the instrumented program compiles, it may be fine simply to keep using
              <sys/sdt.h> but eschew extraction of a few individual  parameters.   In  the  worst
              case,   disable   <sys/sdt.h>   macros   entirely   to   eschew   the   compiled-in
              instrumentation.  If DWARF debuginfo  was  generated  and  preserved,  a  systemtap
              script  could  refer  to  the  underlying  source  context variables instead of the
              positional STAP_PROBE parameters.

SEE ALSO

       stap(1),
       stapprobes(3stap),
       error::dwarf(7stap),
       http://gcc.gnu.org/onlinedocs/gcc/Constraints.html,
       http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation,
       error::reporting(7stap)

                                                                                ERROR::SDT(7stap)