On 05/07/17 16:38, Sandra Loosemore wrote:
> On 07/05/2017 01:36 AM, Torsten Duwe wrote:
>> Changes since v9:
>>
>> * Do not store (declare static) the nop pattern template string.
>> In the future, it might depend on the particular function
>> being emitted. Fetch it freshly each time instead.
>>
>> * On platforms without named sections, simply omit the recording
>> of the nop locations. Run-time instrumentation can still fiddle
>> it out, if desired. Document this behaviour in a half sentence.
>>
>> * Move the hook documentation to where it belongs. Texi file (re-)
>> generation should work cleanly now.
>>
>> * Documentation clarified as requested.
>>
>> Torsten
>>
>> [snip]
>>
>> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
>> index 03ba8fc436c..a4c3c98b9f5 100644
>> --- a/gcc/doc/extend.texi
>> +++ b/gcc/doc/extend.texi
>> @@ -3105,6 +3105,27 @@ that affect more than one function.
>> This attribute should be used for debugging purposes only. It is not
>> suitable in production code.
>>
>> +@item patchable_function_entry
>> +@cindex @code{patchable_function_entry} function attribute
>> +@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.
>> +
>> +The @code{patchable_function_entry} function attribute can be used to
>> +change the number of NOPs to any desired value. The two-value syntax
>> +is the same as for the command-line switch
>> +@option{-fpatchable-function-entry=N,M}, generating @var{N} NOPs, with
>> +the function entry point before the @var{M}th NOP instruction.
>> +@var{M} defaults to 0 if omitted e.g. function entry point is before
>> +the first NOP.
>> +
>> +If patchable function entries are enabled globally using the command
>> +line option @option{-fpatchable-function-entry=N,M}, then all functions
>
> s/command line option/command-line option
>
>> +that are part of the instrumentation framework must disable
>> +instrumentation with the attribute @code{patchable_function_entry (0)}
>> +to prevent recursion.
>
> The functions don't disable instrumentation, programmers disable the
> instrumentation on functions. Rewrite this clause as
>
> ...then you must disable instrumentation on all functions that are part
> of the instrumentation framework with the attribute...
>
>> diff --git a/gcc/doc/invoke.texi b/gcc/doc/invoke.texi
>> index 04cecf94405..1b8a4555b33 100644
>> --- a/gcc/doc/invoke.texi
>> +++ b/gcc/doc/invoke.texi
>> @@ -11520,6 +11520,34 @@ 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 -fpatchable-function-entry=@var{N}[,@var{M}]
>> +@opindex fpatchable-function-entry
>> +Generate @var{N} NOPs right at the beginning
>> +of each function, with the function entry point before the @var{M}th
>> NOP.
>> +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 controllable indirectly via
>> +the number of NOPs; the NOP instruction used corresponds to the
>> instruction
>> +emitted by the internal GCC back-end interface @code{gen_nop}. This
>> behavior
>> +is target-specific and may also depend on the architecture variant
>> and/or
>> +other compilation options.
>> +
>> +For run-time identification, the starting addresses of these areas,
>> +which correspond to their respective function entries minus @var{M},
>> +are additionally collected in the @code{__patchable_function_entries}
>> +section of the resulting binary, if the platform supports it.
>> +
>> +Note that the value of @code{__attribute__ ((patchable_function_entry
>> +(N,M)))} takes precedence over command-line option
>> +@option{-fpatchable-function-entry=N,M}. This can be used to increase
>> +the area size or to remove it completely on a single function.
>> +If @code{N=0}, no pad location is recorded.
>> +
>> +The NOP instructions are inserted at --- and maybe before, depending on
>> +@var{M} --- the function entry address, even before the prologue.
>
> No spaces around the em-dashes '---'.
>
>> +DEFHOOK
>> +(print_patchable_function_entry,
>> + "Generate a patchable area at the function start, consisting of\n\
>> +@var{patch_area_size} NOP instructions. If the target supports named\n\
>> +sections and if @var{record_p} is true, insert a pointer to the
>> current\n\
>> +location in the table of patchable functions. This table will then
>> be held\n\
>> +in a special section called @code{__patchable_function_entries}.",
>
> I don't understand when "then" might be. Can you rewrite this in the
> present tense? "This table is held..."
>
> -Sandra
>
Perhaps you should also mention that this is what the default
implementation of the hook does. So:
The default implementation of the hook places the table of pointers in
the special section named @code{__patchable_function_entries}.
The point is that another implementation of the hook might put them in a
different section, or even record them entirely differently.
R.
