dtrace.h

Sun Solaris 10 中的 DTrace 组件的源代码。请参看: http://www.sun.com/software/solaris/observability.jsp

 * that the provider passes to the framework when registering itself.  This
 * structure consists of the following members:
 *
 *   dtps_provide()          <-- Provide all probes, all modules
 *   dtps_provide_module()   <-- Provide all probes in specified module
 *   dtps_enable()           <-- Enable specified probe
 *   dtps_disable()          <-- Disable specified probe
 *   dtps_suspend()          <-- Suspend specified probe
 *   dtps_resume()           <-- Resume specified probe
 *   dtps_getargdesc()       <-- Get the argument description for args[X]
 *   dtps_getargval()        <-- Get the value for an argX or args[X] variable
 *   dtps_usermode()         <-- Find out if the probe was fired in user mode
 *   dtps_destroy()          <-- Destroy all state associated with this probe
 *
 * 1.2  void dtps_provide(void *arg, const dtrace_probedesc_t *spec)
 *
 * 1.2.1  Overview
 *
 *   Called to indicate that the provider should provide all probes.  If the
 *   specified description is non-NULL, dtps_provide() is being called because
 *   no probe matched a specified probe -- if the provider has the ability to
 *   create custom probes, it may wish to create a probe that matches the
 *   specified description.
 *
 * 1.2.2  Arguments and notes
 *
 *   The first argument is the cookie as passed to dtrace_register().  The
 *   second argument is a pointer to a probe description that the provider may
 *   wish to consider when creating custom probes.  The provider is expected to
 *   call back into the DTrace framework via dtrace_probe_create() to create
 *   any necessary probes.  dtps_provide() may be called even if the provider
 *   has made available all probes; the provider should check the return value
 *   of dtrace_probe_create() to handle this case.  Note that the provider need
 *   not implement both dtps_provide() and dtps_provide_module(); see
 *   "Arguments and Notes" for dtrace_register(), below.
 *
 * 1.2.3  Return value
 *
 *   None.
 *
 * 1.2.4  Caller's context
 *
 *   dtps_provide() is typically called from open() or ioctl() context, but may
 *   be called from other contexts as well.  The DTrace framework is locked in
 *   such a way that providers may not register or unregister.  This means that
 *   the provider may not call any DTrace API that affects its registration with
 *   the framework, including dtrace_register(), dtrace_unregister(),
 *   dtrace_invalidate(), and dtrace_condense().  However, the context is such
 *   that the provider may (and indeed, is expected to) call probe-related
 *   DTrace routines, including dtrace_probe_create(), dtrace_probe_lookup(),
 *   and dtrace_probe_arg().
 *
 * 1.3  void dtps_provide_module(void *arg, struct modctl *mp)
 *
 * 1.3.1  Overview
 *
 *   Called to indicate that the provider should provide all probes in the
 *   specified module.
 *
 * 1.3.2  Arguments and notes
 *
 *   The first argument is the cookie as passed to dtrace_register().  The
 *   second argument is a pointer to a modctl structure that indicates the
 *   module for which probes should be created.
 *
 * 1.3.3  Return value
 *
 *   None.
 *
 * 1.3.4  Caller's context
 *
 *   dtps_provide_module() may be called from open() or ioctl() context, but
 *   may also be called from a module loading context.  mod_lock is held, and
 *   the DTrace framework is locked in such a way that providers may not
 *   register or unregister.  This means that the provider may not call any
 *   DTrace API that affects its registration with the framework, including
 *   dtrace_register(), dtrace_unregister(), dtrace_invalidate(), and
 *   dtrace_condense().  However, the context is such that the provider may (and
 *   indeed, is expected to) call probe-related DTrace routines, including
 *   dtrace_probe_create(), dtrace_probe_lookup(), and dtrace_probe_arg().  Note
 *   that the provider need not implement both dtps_provide() and
 *   dtps_provide_module(); see "Arguments and Notes" for dtrace_register(),
 *   below.
 *
 * 1.4  void dtps_enable(void *arg, dtrace_id_t id, void *parg)
 *
 * 1.4.1  Overview
 *
 *   Called to enable the specified probe.
 *
 * 1.4.2  Arguments and notes
 *
 *   The first argument is the cookie as passed to dtrace_register().  The
 *   second argument is the identifier of the probe to be enabled.  The third
 *   argument is the probe argument as passed to dtrace_probe_create().
 *   dtps_enable() will be called when a probe transitions from not being
 *   enabled at all to having one or more ECB.  The number of ECBs associated
 *   with the probe may change without subsequent calls into the provider.
 *   When the number of ECBs drops to zero, the provider will be explicitly
 *   told to disable the probe via dtps_disable().  dtrace_probe() should never
 *   be called for a probe identifier that hasn't been explicitly enabled via
 *   dtps_enable().
 *
 * 1.4.3  Return value
 *
 *   None.
 *
 * 1.4.4  Caller's context
 *
 *   The DTrace framework is locked in such a way that it may not be called
 *   back into at all.  cpu_lock is held.  mod_lock is not held and may not
 *   be acquired.
 *
 * 1.5  void dtps_disable(void *arg, dtrace_id_t id, void *parg)
 *
 * 1.5.1  Overview
 *
 *   Called to disable the specified probe.
 *
 * 1.5.2  Arguments and notes
 *
 *   The first argument is the cookie as passed to dtrace_register().  The
 *   second argument is the identifier of the probe to be disabled.  The third
 *   argument is the probe argument as passed to dtrace_probe_create().
 *   dtps_disable() will be called when a probe transitions from being enabled
 *   to having zero ECBs.  dtrace_probe() should never be called for a probe
 *   identifier that has been explicitly enabled via dtps_disable().
 *
 * 1.5.3  Return value
 *
 *   None.
 *
 * 1.5.4  Caller's context
 *
 *   The DTrace framework is locked in such a way that it may not be called
 *   back into at all.  cpu_lock is held.  mod_lock is not held and may not
 *   be acquired.
 *
 * 1.6  void dtps_suspend(void *arg, dtrace_id_t id, void *parg)
 *
 * 1.6.1  Overview
 *
 *   Called to suspend the specified enabled probe.  This entry point is for
 *   providers that may need to suspend some or all of their probes when CPUs
 *   are being powered on or when the boot monitor is being entered for a
 *   prolonged period of time.
 *
 * 1.6.2  Arguments and notes
 *
 *   The first argument is the cookie as passed to dtrace_register().  The
 *   second argument is the identifier of the probe to be suspended.  The
 *   third argument is the probe argument as passed to dtrace_probe_create().
 *   dtps_suspend will only be called on an enabled probe.  Providers that
 *   provide a dtps_suspend entry point will want to take roughly the action
 *   that it takes for dtps_disable.
 *
 * 1.6.3  Return value
 *
 *   None.
 *
 * 1.6.4  Caller's context
 *
 *   Interrupts are disabled.  The DTrace framework is in a state such that the
 *   specified probe cannot be disabled or destroyed for the duration of
 *   dtps_suspend().  As interrupts are disabled, the provider is afforded
 *   little latitude; the provider is expected to do no more than a store to
 *   memory.
 *
 * 1.7  void dtps_resume(void *arg, dtrace_id_t id, void *parg)
 *
 * 1.7.1  Overview
 *
 *   Called to resume the specified enabled probe.  This entry point is for
 *   providers that may need to resume some or all of their probes after the
 *   completion of an event that induced a call to dtps_suspend().
 *
 * 1.7.2  Arguments and notes
 *
 *   The first argument is the cookie as passed to dtrace_register().  The
 *   second argument is the identifier of the probe to be resumed.  The
 *   third argument is the probe argument as passed to dtrace_probe_create().
 *   dtps_resume will only be called on an enabled probe.  Providers that
 *   provide a dtps_resume entry point will want to take roughly the action
 *   that it takes for dtps_enable.
 *
 * 1.7.3  Return value
 *
 *   None.
 *
 * 1.7.4  Caller's context
 *
 *   Interrupts are disabled.  The DTrace framework is in a state such that the
 *   specified probe cannot be disabled or destroyed for the duration of
 *   dtps_resume().  As interrupts are disabled, the provider is afforded
 *   little latitude; the provider is expected to do no more than a store to
 *   memory.
 *
 * 1.8  void dtps_getargdesc(void *arg, dtrace_id_t id, void *parg,
 *           dtrace_argdesc_t *desc)
 *
 * 1.8.1  Overview
 *
 *   Called to retrieve the argument description for an args[X] variable.
 *
 * 1.8.2  Arguments and notes
 *
 *   The first argument is the cookie as passed to dtrace_register(). The
 *   second argument is the identifier of the current probe. The third
 *   argument is the probe argument as passed to dtrace_probe_create(). The
 *   fourth argument is a pointer to the argument description.  This
 *   description is both an input and output parameter:  it contains the
 *   index of the desired argument in the dtargd_ndx field, and expects
 *   the other fields to be filled in upon return.  If there is no argument
 *   corresponding to the specified index, the dtargd_ndx field should be set
 *   to DTRACE_ARGNONE.
 *
 * 1.8.3  Return value
 *
 *   None.  The dtargd_ndx, dtargd_native, dtargd_xlate and dtargd_mapping
 *   members of the dtrace_argdesc_t structure are all output values.
 *
 * 1.8.4  Caller's context
 *
 *   dtps_getargdesc() is called from ioctl() context. mod_lock is held, and
 *   the DTrace framework is locked in such a way that providers may not
 *   register or unregister.  This means that the provider may not call any
 *   DTrace API that affects its registration with the framework, including
 *   dtrace_register(), dtrace_unregister(), dtrace_invalidate(), and
 *   dtrace_condense().
 *
 * 1.9  uint64_t dtps_getargval(void *arg, dtrace_id_t id, void *parg,
 *               int argno, int aframes)
 *
 * 1.9.1  Overview
 *
 *   Called to retrieve a value for an argX or args[X] variable.
 *
 * 1.9.2  Arguments and notes
 *
 *   The first argument is the cookie as passed to dtrace_register(). The
 *   second argument is the identifier of the current probe. The third
 *   argument is the probe argument as passed to dtrace_probe_create(). The
 *   fourth argument is the number of the argument (the X in the example in
 *   1.9.1). The fifth argument is the number of stack frames that were used
 *   to get from the actual place in the code that fired the probe to
 *   dtrace_probe() itself, the so-called artificial frames. This argument may
 *   be used to descend an appropriate number of frames to find the correct
 *   values. If this entry point is left NULL, the dtrace_getarg() built-in
 *   function is used.
 *
 * 1.9.3  Return value
 *
 *   The value of the argument.
 *
 * 1.9.4  Caller's context
 *
 *   This is called from within dtrace_probe() meaning that interrupts
 *   are disabled. No locks should be taken within this entry point.
 *
 * 1.10  int dtps_usermode(void *arg, dtrace_id_t id, void *parg)
 *
 * 1.10.1  Overview
 *
 *   Called to determine if the probe was fired in a user context.
 *
 * 1.10.2  Arguments and notes
 *
 *   The first argument is the cookie as passed to dtrace_register(). The
 *   second argument is the identifier of the current probe. The third
 *   argument is the probe argument as passed to dtrace_probe_create().  This
 *   entry point must not be left NULL for providers whose probes allow for
 *   mixed mode tracing, that is to say those probes that can fire during
 *   kernel- _or_ user-mode execution
 *
 * 1.10.3  Return value
 *
 *   A boolean value.
 *
 * 1.10.4  Caller's context
 *
 *   This is called from within dtrace_probe() meaning that interrupts
 *   are disabled. No locks should be taken within this entry point.
 *
 * 1.11 void dtps_destroy(void *arg, dtrace_id_t id, void *parg)
 *
 * 1.11.1 Overview
 *
 *   Called to destroy the specified probe.
 *
 * 1.11.2 Arguments and notes
 *
 *   The first argument is the cookie as passed to dtrace_register().  The
 *   second argument is the identifier of the probe to be destroyed.  The third
 *   argument is the probe argument as passed to dtrace_probe_create().  The
 *   provider should free all state associated with the probe.  The framework
 *   guarantees that dtps_destroy() is only called for probes that have either
 *   been disabled via