On 02/17/2017 09:57 AM, Torsten Duwe wrote:
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 3d1546a..ef7e985 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -3076,6 +3076,23 @@ that affect more than one function.
This attribute should be used for debugging purposes only. It is not
suitable in production code.
+@item prolog_pad
+@cindex @code{prolog_pad} function attribute
I'm only a documentation maintainer so this is out of my area of
responsibility, but I really wish we could rename the attribute and
command-line option. Per
per https://gcc.gnu.org/codingconventions.html#Spelling
the correct spelling is "prologue".
+@cindex extra NOP instructions at the function entry point
+In case the target's text segment can be made writable at run time
+by any means, padding the function entry with a number of NOPs can
+be used to provide a universal tool for instrumentation. Usually,
+prolog padding is enabled globally using the @option{-fprolog-pad=N,M}
definitely s/prolog/prologue/ in the running text here.
+command-line switch, and disabled with attribute @code{prolog_pad (0)}
+for functions that are part of the actual instrumentation framework.
+This conveniently avoids an endless recursion.
+The @code{prolog_pad} function attribute can be used to
+change the pad size to any desired value. The two-value syntax is
+the same as for the command-line switch @option{-fprolog-pad=N,M},
Add a cross-reference here.
+generating a NOP pad of size @var{N}, with the function entry point
Sizes are usually expressed in bytes. I think some other unit is
intended here, though, so I'd avoid "size" and use some other way to
describe it. Maybe "generating a pad of @var{N} NOP instructions".
+@var{M} NOP instructions into the pad. @var{M} defaults to 0
+if omitted e.g. function entry point is before the first NOP.
+
@item pure
@cindex @code{pure} function attribute
@cindex functions that have no side effects
diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
index 56ca53f..75a7e2c 100644
--- a/gcc/doc/invoke.texi
+++ b/gcc/doc/invoke.texi
@@ -11370,6 +11370,31 @@ of the function name, it is considered to be a match.
For C99 and C++
extended identifiers, the function name must be given in UTF-8, not
using universal character names.
+@item -fprolog-pad=@var{N}[,@var{M}]
+@opindex fprolog-pad
+Generate a pad of @var{N} NOPs right at the beginning
+of each function, with the function entry point @var{M} NOPs into
+the pad. If @var{M} is omitted, it defaults to @code{0} so the
+function entry points to the address just at the first NOP.
+The NOP instructions reserve extra space which can be used to patch in
+any desired instrumentation at run time, provided that the code segment
+is writable. The amount of space is only controllable indirectly via
+the number of NOPs, so implementers are advised to use the smallest
+NOP instruction available for the current CPU mode should there be a
+choice, in order to achieve the finest granularity.
The audience of the GCC user manual is users, not implementers. If this
is really just "advice" on what the option should do in the presence of
multiple instruction sizes, and not a firm requirement, then rewrite as
something like:
The amount of space reserved is expressed as the number of NOP
instructions to insert. On targets that have multiple instruction sizes,
typically the smallest NOP instruction available for the current CPU
mode is used to achieve the finest granularity.
...except that I don't think "CPU mode" is really what you intend here.
E.g. on nios2, support for 16-bit instructions is a code generation
option (-mcdx) rather than a -mcpu= or -march= option, and there is
certainly no runtime processor mode selection involved.
If this is really a firm requirement, I think the burden is on you to
identify all backends that have multiple NOP sizes for which the default
hook implementation won't give the required behavior, and either provide
an appropriate hook or work with the backend maintainers to develop one.
I'd put a paragraph break here, before:
+For run-time identification, the starting addresses
+of these pads, which correspond to their respective function entries
+minus @var{M}, are additionally collected in the @code{__prolog_pads_loc}
+section of the resulting binary.
+
+Note that the value of @code{__attribute__ ((prolog_pad (N,M)))} takes
+precedence over command-line option @option{-fprolog-pad=N,M}.
@var{N} and @var{M} in both places, please. And add a cross-reference.
+This can be used to increase the pad size or to remove it completely
+on a single function. If @code{N=0}, no pad location is recorded.
That's sloppy markup. How about
If @var{N} is zero, ....
+The NOP instructions are inserted at (and maybe before) the function entry
+address, even before the prologue.
+
@end table
diff --git a/gcc/doc/tm.texi b/gcc/doc/tm.texi
index 348fd68..5155d10 100644
--- a/gcc/doc/tm.texi
+++ b/gcc/doc/tm.texi
@@ -4566,6 +4566,10 @@ will select the smallest suitable mode.
This section describes the macros that output function entry
(@dfn{prologue}) and exit (@dfn{epilogue}) code.
+@deftypefn {Target Hook} void TARGET_ASM_PRINT_PROLOG_PAD (FILE *@var{file},
unsigned HOST_WIDE_INT @var{pad_size}, bool @var{record_p})
+Generate prologue pad
Sigh again. Every other prologue-related target hook uses the PROLOGUE
spelling. :-S
Missing punctuation at the end of the sentence, and there's not nearly
enough information about what this hook should do.
Also, I suggest moving this down in the section instead of listing it
first, because of the usual principle of giving the most important
information first.
+@end deftypefn
+
@deftypefn {Target Hook} void TARGET_ASM_FUNCTION_PROLOGUE (FILE *@var{file},
HOST_WIDE_INT @var{size})
If defined, a function that outputs the assembler code for entry to a
function. The prologue is responsible for setting up the stack frame,
-Sandra
