annobin: Plugins

1 
1 2 How to add Binary Annotations to your application.
1 ****************************************************
1 
1 Normally the option to enable the recording of binary annotation notes
1 is enabled automatically by the build system, so no user intervention is
1 required.  On Fedora and RHEL based systems this is handled by the
1 'redhat-rpm-config' package.
1 
1    Currently the binary annotations are generated by a plugin to the
1 compiler ('GCC', 'clang' or 'llvm').  This does mean that files that are
1 not compiled by any of these compilers will not gain any annotations,
1 although there is an optional assembler switch to add some basic notes
1 if none are present in the input files.
1 
1    If the build system being used does not automatically enable the
1 'annobin' plugin then it can be specifically added to the compiler
1 command line by adding the '-fplugin=annobin' (for gcc) or
1 '-fplugin=annobin-for-clang' (for clang) or '-fplugin=annobin-for-llvm'
1 (for LLVM) option.  It may also be necessary to tell the compiler where
1 to find the plugin by adding the '-iplugindir=' option, although this
1 should only be necessary if the plugin is installed in an unusual place.
1 
1    If it is desired to disable the recording of binary annotations then
1 the '-fplugin-arg-annobin-disable' (for 'gcc') or '-Xclang
1 -plugin-arg-annobin-disable' (for 'clang' or 'llvm') can be used.  Note
1 - these options must be placed _after_ the '-fplugin=annobin' option.
1 
1    On Fedora and RHEL systems the plugin can be disabled entirely for
1 all compilations in a package by adding '%undefine _annotated_build' to
1 the spec file.
1 
1    The plugin accepts a small selection of command line arguments, all
1 accessed by passing '-fplugin-arg-annobin-<option>' (for 'gcc') or
1 '-Xclang -plugin-arg-annobin-<option>' (for 'clang' or 'llvm') on the
1 command line.  These options must be placed on the command line after
1 the plugin itself is mentioned.  Note - not all versions of the plugin
1 accept all of these options.  The options are:
1 
1 'disable'
1 'enable'
1      Either disable or enable the plugin.  The default is for the plugin
1      to be enabled.
1 
1 'help'
1      Display a list of supported options on the standard output.  This
1      is in addition to whatever else the plugin has been instructed to
1      do.
1 
1 'version'
1      Display the version of the plugin on the standard output.  This is
1      in addition to whatever else the plugin has been instructed to do.
1 
1 'verbose'
1      Report the actions that the plugin is taking.  If invoked for a
1      second time on the command line the plugin will be very verbose.
1 
1 'function-verbose'
1      Report the generation of function specific notes.  This indicates
1      that the named function was compiled with different options from
1      those that were globally enabled.
1 
1 'stack-size-notes'
1 'no-stack-size-notes'
1      Do, or do not, record information about the stack requirements of
1      functions in the executable.  This feature is disabled by default
1      as these notes can take up a lot of extra room if the executable
1      contains a lot of functions.
1 
1 'stack-threshold=N'
1      If stack size requirements are being recorded then this option sets
1      the minimum value to record.  Functions which require less than 'N'
1      bytes of static stack space will not have their requirements
1      recorded.  If not set, then 'N' defaults to 1024.
1 
1 'global-file-syms'
1 'no-global-file-syms'
1      If enabled the 'global-file-syms' option will create globally
1      visible, unique symbols to mark the start and end of the compiled
1      code.  This can be desirable if a program consists of multiple
1      source files with the same name, or if it links to a library that
1      was built with source files of the same name as the program itself.
1      The disadvantage of this feature however is that the unique names
1      are based upon the time of the build, so repeated builds of the
1      same source will have different symbol names inside it.  This
1      breaks the functionality of the build-id system which is meant to
1      identify similar builds created at different times.  This feature
1      is disabled by default, and if enabled can be disabled again via
1      the 'no-global-file-syms' option.
1 
1 'attach'
1 'no-attach'
1      When gcc compiles code with the '-ffunction-sections' option active
1      it will place each function into its own section.  When the
1      'annobin' 'attach' option is active the plugin will attempt to
1      attach the function section to a group containing the notes and
1      relocations for the function.  In that way, if the linker decides
1      to discard the function, it will also know that it should discard
1      the notes and relocations as well.
1 
1      The default is 'attach', but this can be disabled via the
1      'no-attach' option.  Note however that if both 'attach' and
1      'link-order' are disabled then note generation for function
1      sections will not work properly.
1 
1 'link-order'
1 'no-link-order'
1      As an alternative to using section groups and a special assembler
1      directive the plugin can use a feature of the ELF 'SHF_LINK_ORDER'
1      flag which tells the linker that it should discard a section if the
1      section it is linked to is also being discarded.  This behaviour is
1      enabled by the 'link-order' option.
1 
1 'rename'
1      Adds an extra prefix to the symbol names generated by the 'annobin'
1      plugin.  This allows the plugin to be run twice on the same
1      executable, which can be useful for debugging and build testing.
1 
1 'active-checks'
1 'no-active-checks'
1      The 'annobin' plugin will normally generate a warning message if it
1      detects that neither the '-D_FORTIFY_SOURCE=2' nor the
1      '-D_FORTIFY_SOURCE=3' options have been provided on the command
1      line and '-flto' has been enabled.  This is because LTO compilation
1      hides preprocessor options, so information about them cannot be
1      passed on to the 'annocheck' tool.
1 
1      The 'active-checks' option changes the warning message into an
1      error message, just as if '-Werror' had been specified.
1 
1      The 'no-active-checks' option disables the warning message
1      entirely.
1 
1      Note - in the future the 'annobin' plugin might be extended to
1      produce warning messages for other missing command line options.
1 
1      Note - as a workaround for certain tests generated by the
1      'autoconf' tool the warning message will not be produced if the
1      input source filename starts with 'conftest.'.  In these cases
1      autoconf is usually checking to see if a warning will be produced
1      for some other reason, and so the 'annobin' warning would get in
1      the way.  If the 'active-checks' option has been enabled however,
1      an error message will still be generated.
1 
1 'dynamic-notes'
1 'no-dynamic-notes'
1 'static-notes'
1 'no-static-notes'
1      These options are deprecated.
1 
1 'ppc64-nops'
1 'no-ppc64-nops'
1      This option either enables or disables the insertion of NOP
1      instructions in the some of the code sections of PowerPC64
1      binaries.  This is necessary to avoid problems with the 'elflint'
1      program which will complain about binaries built without this
1      option enabled.  The option is enabled by default, but since it
1      does increase the size of compiled programs by a small amount, the
1      'no-ppc64-nops' is provided in order to turn it off.
1 
1    The plugins record information appropriate to the compiler that is
1 running them.  So the 'gcc' plugin records information about the
1 following options:
1 '-D_FORTIFY_SOURCE=[2|3]'
1 '-D_GLIBCXX_ASSERTIONS'
1 '-O'
1 '-Wall'
1 '-fPIC'
1 '-fPIE'
1 '-fcf-protection'
1 '-finstrument_functions'
1 '-flto'
1 '-fomit-frame-pointer'
1 '-fprofile'
1 '-fprofile-arcs'
1 '-fsanitize'
1 '-fshort-enums'
1 '-fstack-clash-protection'
1 '-fstack-protector'
1 '-g'
1 '-mbranch-protection (AArch64)'
1 '-mstack-realign (i386)'
1 '-mtls-size (PowerPC)'
1 
1    The 'Clang' plugin records information on the following command line
1 options:
1 '-O'
1 '-Wall'
1 '-fPIC'
1 '-fPIE'
1 '-fcf-protection-branch'
1 '-fcf-protection-return'
1 '-fsanitize=cfi-cast-strict'
1 '-fsanitize=safe-stack'
1 '-fspeculative-load-hardening'
1 '-fstack-protector-strong'
1 
1    Note - if LTO compilation is enabled (-flto) then any data recorded
1 by the Clang plugin is ignored when the object file is recompiled by the
1 LLVM backend.  Hence when using LTO and Clang it is best to enable the
1 LLVM plugin.
1 
1    The 'LLVM' plugin records information on the following command line
1 options:
1 '-D_FORTIFY_SOURCE=[2|3]'
1 '-O'
1 '-Wall'
1 '-flto'
1 '-fPIC'
1 '-fPIE'
1 '-fcf-protection-branch'
1 '-fcf-protection-return'
1 '-fsanitize=safe-stack'
1 '-fstack-protector-strong'
1 '-g'
1