ERROR::SDT(7stap)                                            ERROR::SDT(7stap)

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)