[PATCH] ftrace: Document ftrace command line limitations

[PATCH] ftrace: Document ftrace command line limitations

[Peter Hurley]

When using the function or function_graph tracers from the command
line, certain command line options have limitations.

Document that only kernel built-in functions can be filtered via
ftrace_filter= or ftrace_graph_filter=. Also document that tracer-
specific options cannot be set on the command line via trace_options.

Signed-off-by: Peter Hurley <peter@hurleysoftware.com>
---
 Documentation/kernel-parameters.txt | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt
index 4c81a86..6f9dfa0 100644
--- a/Documentation/kernel-parameters.txt
+++ b/Documentation/kernel-parameters.txt
@@ -1121,6 +1121,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
 			list of functions. This list can be changed at run
 			time by the set_ftrace_filter file in the debugfs
 			tracing directory.
+			Only built-in functions can be traced when specified
+			this way.
 
 	ftrace_notrace=[function-list]
 			[FTRACE] Do not trace the functions specified in
@@ -1134,6 +1136,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
 			function-list is a comma separated list of functions
 			that can be changed at run time by the
 			set_graph_function file in the debugfs tracing directory.
+			Only built-in functions can be traced when specified
+			this way.
 
 	ftrace_graph_notrace=[function-list]
 			[FTRACE] Do not trace from the functions specified in
@@ -3521,6 +3525,10 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
 
 			      trace_options=stacktrace
 
+			Tracer-specific options are ignored when set this way.
+			For example, the 'func_stack_trace' option cannot be
+			set here.
+
 			See also Documentation/trace/ftrace.txt "trace options"
 			section.
 
-- 
2.1.1

Re: [PATCH] ftrace: Document ftrace command line limitations

[Steven Rostedt]

On Mon,  3 Nov 2014 20:45:25 -0500
Peter Hurley <peter@hurleysoftware.com> wrote:

> When using the function or function_graph tracers from the command
> line, certain command line options have limitations.
> 
> Document that only kernel built-in functions can be filtered via
> ftrace_filter= or ftrace_graph_filter=. Also document that tracer-
> specific options cannot be set on the command line via trace_options.

It's not just a command line limitation. The command line behaves
exactly like set_ftrace_filter does. That is, it only affects the
functions that are loaded when the filter is modified. It never updates
functions that will be loaded when modules are.

Adding this documentation makes it seem that set_ftrace_filter has the
ability to update functions that were not loaded yet. This is not true.
The command line filtering behaves exactly like set_ftrace_filter does.
It only enables the functions that are loaded at the time the function
is set. Which was at boot up, and it just happens to be only built in
functions at that time.

-- Steve



> 
> Signed-off-by: Peter Hurley <peter@hurleysoftware.com>
> ---
>  Documentation/kernel-parameters.txt | 8 ++++++++
>  1 file changed, 8 insertions(+)
> 
> diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt
> index 4c81a86..6f9dfa0 100644
> --- a/Documentation/kernel-parameters.txt
> +++ b/Documentation/kernel-parameters.txt
> @@ -1121,6 +1121,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
>  			list of functions. This list can be changed at run
>  			time by the set_ftrace_filter file in the debugfs
>  			tracing directory.
> +			Only built-in functions can be traced when specified
> +			this way.
>  
>  	ftrace_notrace=[function-list]
>  			[FTRACE] Do not trace the functions specified in
> @@ -1134,6 +1136,8 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
>  			function-list is a comma separated list of functions
>  			that can be changed at run time by the
>  			set_graph_function file in the debugfs tracing directory.
> +			Only built-in functions can be traced when specified
> +			this way.
>  
>  	ftrace_graph_notrace=[function-list]
>  			[FTRACE] Do not trace from the functions specified in
> @@ -3521,6 +3525,10 @@ bytes respectively. Such letter suffixes can also be entirely omitted.
>  
>  			      trace_options=stacktrace
>  
> +			Tracer-specific options are ignored when set this way.
> +			For example, the 'func_stack_trace' option cannot be
> +			set here.
> +
>  			See also Documentation/trace/ftrace.txt "trace options"
>  			section.
>  

Re: [PATCH] ftrace: Document ftrace command line limitations

[Peter Hurley]

On 11/03/2014 09:14 PM, Steven Rostedt wrote:
> On Mon,  3 Nov 2014 20:45:25 -0500
> Peter Hurley <peter@hurleysoftware.com> wrote:
> 
>> When using the function or function_graph tracers from the command
>> line, certain command line options have limitations.
>>
>> Document that only kernel built-in functions can be filtered via
>> ftrace_filter= or ftrace_graph_filter=. Also document that tracer-
>> specific options cannot be set on the command line via trace_options.
> 
> It's not just a command line limitation. The command line behaves
> exactly like set_ftrace_filter does. That is, it only affects the
> functions that are loaded when the filter is modified. It never updates
> functions that will be loaded when modules are.
> 
> Adding this documentation makes it seem that set_ftrace_filter has the
> ability to update functions that were not loaded yet. This is not true.
> The command line filtering behaves exactly like set_ftrace_filter does.
> It only enables the functions that are loaded at the time the function
> is set. Which was at boot up, and it just happens to be only built in
> functions at that time.

Ah, ok. I'll clarify those two lines and add to the documentation in
Documentation/trace/ftrace.txt