NAME

       fi_hook - The Hook Fabric Provider Utility

OVERVIEW

       The  hooking provider is a utility function that can intercept calls to any provider.  The
       hook provider is always available, but has zero impact on calls  unless  enabled.   It  is
       useful for providing performance data on selected calls or debugging information.

SUPPORTED FEATURES

       Hooking  support  is enabled through the FI_HOOK environment variable.  To enable hooking,
       FI_HOOK must be set to the name of one or more of the available hooking  providers.   When
       multiple  hooks  are  specified, the names must be separated by a semi-colon.  To obtain a
       list of hooking providers available on the current system, one can use the fi_info utility
       with  the '--env' command line option.  Hooking providers are usually identified by 'hook'
       appearing in the provider name.

       Known hooking providers include the following:

       ofi_hook_perf
              This hooks 'fast path' data operation calls.  Performance data is captured on  call
              entrance  and  exit,  in order to provide an average of how long each call takes to
              complete.  See the PERFORMANCE HOOKS section for available performance data.

PERFORMANCE HOOKS

       The  hook  provider  allows  capturing  inline  performance  data  by  accessing  the  CPU
       Performance  Management  Unit  (PMU).   PMU  data  is  only  available  on  Linux systems.
       Additionally,  access  to  PMU  data  may  be  restricted   to   privileged   (super-user)
       applications.

       Performance  data is captured for critical data transfer calls: fi_msg, fi_rma, fi_tagged,
       fi_cq, and fi_cntr.  Captured data is displayed as  logged  data  using  the  FI_LOG_LEVEL
       trace level.  Performance data is logged when the associated fabric is destroyed.

       The  environment  variable  FI_PERF_CNTR  is used to identify which performance counter is
       tracked.  The following counters are available:

       cpu_cycles
              Counts the number of CPU cycles each function takes to complete.

       cpu_instr
              Counts the number of CPU instructions each function takes to complete.  This is the
              default performance counter if none is specified.

LIMITATIONS

       Hooking  functionality  is  not  available  for providers built using the FI_FABRIC_DIRECT
       feature.  That is, directly linking to a provider prevents hooking.

       The hooking provider does not  work  with  triggered  operations.   Application  that  use
       FI_TRIGGER operations that attempt to hook calls will likely crash.

SEE ALSO

       fabric(7), fi_provider(7)

AUTHORS

       OpenFabrics.