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