[cfe-dev] [XRay] RFC: Adding -fxray-{always, never}-instrument=... to Clang

[Dean Michael Berris via cfe-dev]

TL;DR: Adding the [[clang::xray_{always,never}_instrument]] attribute in the declaration/definition of a function is cumbersome for guaranteed instrumentation (or non-instrumentation) of specific functions. We'd like to make the imbuing of this particular attribute a command-line controllable option.

Background
==========

XRay is a function call tracing system that's implemented in LLVM. One part of this system involves enabling users to use a source-level attribute to mark that a function is always instrumented with XRay when building with the `-fxray-instrument` flag enabled. While this is sufficient for some users, it's really inconvenient to have to manually add this attribute to functions that need to be marked with this attribute. Sometimes the decision on whether a function must always be instrumented isn't always known a-priori and could be the result of (or driver for) experimental methods (i.e. building with all functions instrumented, and in next iterations pruning the list down or changing thresholds, etc).

Proposal
=======

We would like to add two flags (`-fxray-always-instrument=` and `-fxray-never-instrument=`) to clang that takes filenames processed similar to how the SanitizerSpecialCaseList [0] feature is handled. We apply first the blacklist, then the whitelist to determine whether a certain functions should be either never instrumented (in the blacklist) or always instrumented (in the whitelist). This allows users to define sets of functions that should be either always or never instrumented with XRay through command-line options.

These lists will only take effect when `-fxray-instrument` is defined when invoking Clang. Currently, we determine whether instrumentation is necessary based on the combination of attributes and whether the instruction count threshold is met (see more at http://llvm.org/docs/XRay.html).

The intent is to have a single class (XRayFunctionFilter) which maintains the special case lists to determine whether to always instrument a function or never instrument a function. We add an instance of class to the ASTContext, and when code-genning function declarations that fall in whitelist will get the "xray_always_instrument" attribute, and if they fall in the blacklist (and not the whitelist) will get the "xray_never_instrument" attribute. The strawman API for determining whether to always or never instrument is as follows:

class XRayFunctionFilter {
public:
  enum class ImbueAttribute {
    NONE, ALWAYS, NEVER, …
  }

  ImbueAttribute shouldImbueAttribute(StringRef FunctionName) const;
private:
  ...
};

An open question is what to do to functions that have the attribute explicitly defined in the source -- whether the whitelist/blacklist overrides those. I'm inclined to think that we should preserve the source-level attribute, but am willing to go either way.

We also have work on-going to enable logging some arguments to function calls (https://reviews.llvm.org/D29704). In these cases we can use the whitelist to also say whether to imbue the attribute using the categories feature in the SanitizerSpecialCaseList file format.

Does the community think this is something worth exploring?

A "natural" extension of this feature would be to just support compile-time attribution of any attribute to any function/class/<insert construct here>. While that might be a more general approach, it seems a bit more invasive and larger a scope than the targeted proposal being made. We aren't opposed per-se to doing this general approach, and believe that the targeted approach we're proposing might inform the design of the more general approach later on.

Thoughts?

[0] http://clang.llvm.org/docs/SanitizerSpecialCaseList.html

-- Dean