Re: [PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[Du, Changbin]

On Fri, Feb 16, 2018 at 12:36:29PM -0500, Steven Rostedt wrote:
> On Fri, 16 Feb 2018 05:49:52 -0700
> Jonathan Corbet  wrote:
> 
> > On Thu, 15 Feb 2018 22:57:05 -0500
> > Steven Rostedt  wrote:
> > 
> > > This document is out of date, and I rather have it updated before we
> > > make it more "available" elsewhere.  
> > 
> > Imagine that, an out-of-date doc in the kernel :)
> > 
> > Seriously, though, I'd argue that (1) it's already highly available, and
> > (2) it's useful now.  And (3) who knows when that update will happen?
> > Unless we have reason to believe that a new version is waiting on the
> > wings, I don't really see why we would want to delay this work.
> 
> Actually, some of these documents I was thinking of labeling as
> "obsolete" or simply removing them. The ftrace-design one is about
> how to port ftrace to other architectures, and I already had to correct
> people that based their work on it.
> 
> Yeah, I really need to get some time to update them, but like everyone
> else, that's just the 90th thing I have to do.
> 
> -- Steve
Reading this doc, I think most of information are still useful for undertading 
the
implemeation. So how abount just put a caution at the begining of doc as below 
defore get updated?
http://docservice.askxiong.com/linux-kernel/trace/ftrace-design.html

Anyway, I just converted them all. I will send them out. Please comemnt if some
of them should be removed. 

-- 
Thanks,
Changbin Du

Re: [PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[Du, Changbin]

On Fri, Feb 16, 2018 at 12:36:29PM -0500, Steven Rostedt wrote:
> On Fri, 16 Feb 2018 05:49:52 -0700
> Jonathan Corbet  wrote:
> 
> > On Thu, 15 Feb 2018 22:57:05 -0500
> > Steven Rostedt  wrote:
> > 
> > > This document is out of date, and I rather have it updated before we
> > > make it more "available" elsewhere.  
> > 
> > Imagine that, an out-of-date doc in the kernel :)
> > 
> > Seriously, though, I'd argue that (1) it's already highly available, and
> > (2) it's useful now.  And (3) who knows when that update will happen?
> > Unless we have reason to believe that a new version is waiting on the
> > wings, I don't really see why we would want to delay this work.
> 
> Actually, some of these documents I was thinking of labeling as
> "obsolete" or simply removing them. The ftrace-design one is about
> how to port ftrace to other architectures, and I already had to correct
> people that based their work on it.
> 
> Yeah, I really need to get some time to update them, but like everyone
> else, that's just the 90th thing I have to do.
> 
> -- Steve
Reading this doc, I think most of information are still useful for undertading 
the
implemeation. So how abount just put a caution at the begining of doc as below 
defore get updated?
http://docservice.askxiong.com/linux-kernel/trace/ftrace-design.html

Anyway, I just converted them all. I will send them out. Please comemnt if some
of them should be removed. 

-- 
Thanks,
Changbin Du

Re: [PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[Steven Rostedt]

On Fri, 16 Feb 2018 05:49:52 -0700
Jonathan Corbet  wrote:

> On Thu, 15 Feb 2018 22:57:05 -0500
> Steven Rostedt  wrote:
> 
> > This document is out of date, and I rather have it updated before we
> > make it more "available" elsewhere.  
> 
> Imagine that, an out-of-date doc in the kernel :)
> 
> Seriously, though, I'd argue that (1) it's already highly available, and
> (2) it's useful now.  And (3) who knows when that update will happen?
> Unless we have reason to believe that a new version is waiting on the
> wings, I don't really see why we would want to delay this work.

Actually, some of these documents I was thinking of labeling as
"obsolete" or simply removing them. The ftrace-design one is about
how to port ftrace to other architectures, and I already had to correct
people that based their work on it.

Yeah, I really need to get some time to update them, but like everyone
else, that's just the 90th thing I have to do.

-- Steve

Re: [PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[Steven Rostedt]

On Fri, 16 Feb 2018 05:49:52 -0700
Jonathan Corbet  wrote:

> On Thu, 15 Feb 2018 22:57:05 -0500
> Steven Rostedt  wrote:
> 
> > This document is out of date, and I rather have it updated before we
> > make it more "available" elsewhere.  
> 
> Imagine that, an out-of-date doc in the kernel :)
> 
> Seriously, though, I'd argue that (1) it's already highly available, and
> (2) it's useful now.  And (3) who knows when that update will happen?
> Unless we have reason to believe that a new version is waiting on the
> wings, I don't really see why we would want to delay this work.

Actually, some of these documents I was thinking of labeling as
"obsolete" or simply removing them. The ftrace-design one is about
how to port ftrace to other architectures, and I already had to correct
people that based their work on it.

Yeah, I really need to get some time to update them, but like everyone
else, that's just the 90th thing I have to do.

-- Steve

Re: [PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[Steven Rostedt]

On Fri, 16 Feb 2018 17:07:26 +0800
"Du, Changbin"  wrote:


> > This document is out of date, and I rather have it updated before we
> > make it more "available" elsewhere.
> >  
> Got you. I plan to convert below docs. Are they out of date, too?
> 
> events-msr.txt, events.txt, mmiotrace.txt, stm.txt, uprobetracer.txt
> events-nmi.txt, intel_th.txt, tracepoint-analysis.txt, events-kmem.txt,
> events-power.txt, ftrace.txt, hwlat_detector.txt, kprobetrace.txt,
> tracepoints.txt.

I'm sure some of them are. I don't have time now to investigate which
ones though.

-- Steve

Re: [PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[Steven Rostedt]

On Fri, 16 Feb 2018 17:07:26 +0800
"Du, Changbin"  wrote:


> > This document is out of date, and I rather have it updated before we
> > make it more "available" elsewhere.
> >  
> Got you. I plan to convert below docs. Are they out of date, too?
> 
> events-msr.txt, events.txt, mmiotrace.txt, stm.txt, uprobetracer.txt
> events-nmi.txt, intel_th.txt, tracepoint-analysis.txt, events-kmem.txt,
> events-power.txt, ftrace.txt, hwlat_detector.txt, kprobetrace.txt,
> tracepoints.txt.

I'm sure some of them are. I don't have time now to investigate which
ones though.

-- Steve

Re: [PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[Jonathan Corbet]

On Thu, 15 Feb 2018 22:57:05 -0500
Steven Rostedt  wrote:

> This document is out of date, and I rather have it updated before we
> make it more "available" elsewhere.

Imagine that, an out-of-date doc in the kernel :)

Seriously, though, I'd argue that (1) it's already highly available, and
(2) it's useful now.  And (3) who knows when that update will happen?
Unless we have reason to believe that a new version is waiting on the
wings, I don't really see why we would want to delay this work.

Thanks,

jon

Re: [PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[Jonathan Corbet]

On Thu, 15 Feb 2018 22:57:05 -0500
Steven Rostedt  wrote:

> This document is out of date, and I rather have it updated before we
> make it more "available" elsewhere.

Imagine that, an out-of-date doc in the kernel :)

Seriously, though, I'd argue that (1) it's already highly available, and
(2) it's useful now.  And (3) who knows when that update will happen?
Unless we have reason to believe that a new version is waiting on the
wings, I don't really see why we would want to delay this work.

Thanks,

jon

Re: [PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[Du, Changbin]

On Thu, Feb 15, 2018 at 10:57:05PM -0500, Steven Rostedt wrote:
> On Fri, 16 Feb 2018 11:12:18 +0800
> changbin...@intel.com wrote:
> 
> > From: Changbin Du 
> > 
> > Signed-off-by: Changbin Du 
> > ---
> >  .../trace/{ftrace-design.txt => ftrace-design.rst} | 248 
> > +++--
> >  Documentation/trace/index.rst  |   2 +
> >  2 files changed, 137 insertions(+), 113 deletions(-)
> >  rename Documentation/trace/{ftrace-design.txt => ftrace-design.rst} (75%)
> > 
> > diff --git a/Documentation/trace/ftrace-design.txt 
> > b/Documentation/trace/ftrace-design.rst
> > similarity index 75%
> > rename from Documentation/trace/ftrace-design.txt
> > rename to Documentation/trace/ftrace-design.rst
> > index a273dd0..0f32a85 100644
> > --- a/Documentation/trace/ftrace-design.txt
> > +++ b/Documentation/trace/ftrace-design.rst
> > @@ -1,6 +1,8 @@
> > -   function tracer guts
> > -   
> > -   By Mike Frysinger
> > +==
> > +Function Tracer Design
> > +==
> > +
> > +:Author: Mike Frysinger
> >  
> 
> This document is out of date, and I rather have it updated before we
> make it more "available" elsewhere.
>
Got you. I plan to convert below docs. Are they out of date, too?

events-msr.txt, events.txt, mmiotrace.txt, stm.txt, uprobetracer.txt
events-nmi.txt, intel_th.txt, tracepoint-analysis.txt, events-kmem.txt,
events-power.txt, ftrace.txt, hwlat_detector.txt, kprobetrace.txt,
tracepoints.txt.
 
> -- Steve

-- 
Thanks,
Changbin Du

Re: [PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[Du, Changbin]

On Thu, Feb 15, 2018 at 10:57:05PM -0500, Steven Rostedt wrote:
> On Fri, 16 Feb 2018 11:12:18 +0800
> changbin...@intel.com wrote:
> 
> > From: Changbin Du 
> > 
> > Signed-off-by: Changbin Du 
> > ---
> >  .../trace/{ftrace-design.txt => ftrace-design.rst} | 248 
> > +++--
> >  Documentation/trace/index.rst  |   2 +
> >  2 files changed, 137 insertions(+), 113 deletions(-)
> >  rename Documentation/trace/{ftrace-design.txt => ftrace-design.rst} (75%)
> > 
> > diff --git a/Documentation/trace/ftrace-design.txt 
> > b/Documentation/trace/ftrace-design.rst
> > similarity index 75%
> > rename from Documentation/trace/ftrace-design.txt
> > rename to Documentation/trace/ftrace-design.rst
> > index a273dd0..0f32a85 100644
> > --- a/Documentation/trace/ftrace-design.txt
> > +++ b/Documentation/trace/ftrace-design.rst
> > @@ -1,6 +1,8 @@
> > -   function tracer guts
> > -   
> > -   By Mike Frysinger
> > +==
> > +Function Tracer Design
> > +==
> > +
> > +:Author: Mike Frysinger
> >  
> 
> This document is out of date, and I rather have it updated before we
> make it more "available" elsewhere.
>
Got you. I plan to convert below docs. Are they out of date, too?

events-msr.txt, events.txt, mmiotrace.txt, stm.txt, uprobetracer.txt
events-nmi.txt, intel_th.txt, tracepoint-analysis.txt, events-kmem.txt,
events-power.txt, ftrace.txt, hwlat_detector.txt, kprobetrace.txt,
tracepoints.txt.
 
> -- Steve

-- 
Thanks,
Changbin Du

Re: [PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[Steven Rostedt]

On Fri, 16 Feb 2018 11:12:18 +0800
changbin...@intel.com wrote:

> From: Changbin Du 
> 
> Signed-off-by: Changbin Du 
> ---
>  .../trace/{ftrace-design.txt => ftrace-design.rst} | 248 
> +++--
>  Documentation/trace/index.rst  |   2 +
>  2 files changed, 137 insertions(+), 113 deletions(-)
>  rename Documentation/trace/{ftrace-design.txt => ftrace-design.rst} (75%)
> 
> diff --git a/Documentation/trace/ftrace-design.txt 
> b/Documentation/trace/ftrace-design.rst
> similarity index 75%
> rename from Documentation/trace/ftrace-design.txt
> rename to Documentation/trace/ftrace-design.rst
> index a273dd0..0f32a85 100644
> --- a/Documentation/trace/ftrace-design.txt
> +++ b/Documentation/trace/ftrace-design.rst
> @@ -1,6 +1,8 @@
> - function tracer guts
> - 
> - By Mike Frysinger
> +==
> +Function Tracer Design
> +==
> +
> +:Author: Mike Frysinger
>  

This document is out of date, and I rather have it updated before we
make it more "available" elsewhere.

-- Steve

Re: [PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[Steven Rostedt]

On Fri, 16 Feb 2018 11:12:18 +0800
changbin...@intel.com wrote:

> From: Changbin Du 
> 
> Signed-off-by: Changbin Du 
> ---
>  .../trace/{ftrace-design.txt => ftrace-design.rst} | 248 
> +++--
>  Documentation/trace/index.rst  |   2 +
>  2 files changed, 137 insertions(+), 113 deletions(-)
>  rename Documentation/trace/{ftrace-design.txt => ftrace-design.rst} (75%)
> 
> diff --git a/Documentation/trace/ftrace-design.txt 
> b/Documentation/trace/ftrace-design.rst
> similarity index 75%
> rename from Documentation/trace/ftrace-design.txt
> rename to Documentation/trace/ftrace-design.rst
> index a273dd0..0f32a85 100644
> --- a/Documentation/trace/ftrace-design.txt
> +++ b/Documentation/trace/ftrace-design.rst
> @@ -1,6 +1,8 @@
> - function tracer guts
> - 
> - By Mike Frysinger
> +==
> +Function Tracer Design
> +==
> +
> +:Author: Mike Frysinger
>  

This document is out of date, and I rather have it updated before we
make it more "available" elsewhere.

-- Steve

[PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[changbin . du]

From: Changbin Du 

Signed-off-by: Changbin Du 
---
 .../trace/{ftrace-design.txt => ftrace-design.rst} | 248 +++--
 Documentation/trace/index.rst  |   2 +
 2 files changed, 137 insertions(+), 113 deletions(-)
 rename Documentation/trace/{ftrace-design.txt => ftrace-design.rst} (75%)

diff --git a/Documentation/trace/ftrace-design.txt 
b/Documentation/trace/ftrace-design.rst
similarity index 75%
rename from Documentation/trace/ftrace-design.txt
rename to Documentation/trace/ftrace-design.rst
index a273dd0..0f32a85 100644
--- a/Documentation/trace/ftrace-design.txt
+++ b/Documentation/trace/ftrace-design.rst
@@ -1,6 +1,8 @@
-   function tracer guts
-   
-   By Mike Frysinger
+==
+Function Tracer Design
+==
+
+:Author: Mike Frysinger
 
 Introduction
 
@@ -21,8 +23,8 @@ Prerequisites
 -
 
 Ftrace relies on these features being implemented:
- STACKTRACE_SUPPORT - implement save_stack_trace()
- TRACE_IRQFLAGS_SUPPORT - implement include/asm/irqflags.h
+  - STACKTRACE_SUPPORT - implement save_stack_trace()
+  - TRACE_IRQFLAGS_SUPPORT - implement include/asm/irqflags.h
 
 
 HAVE_FUNCTION_TRACER
@@ -32,9 +34,11 @@ You will need to implement the mcount and the ftrace_stub 
functions.
 
 The exact mcount symbol name will depend on your toolchain.  Some call it
 "mcount", "_mcount", or even "__mcount".  You can probably figure it out by
-running something like:
+running something like::
+
$ echo 'main(){}' | gcc -x c -S -o - - -pg | grep mcount
callmcount
+
 We'll make the assumption below that the symbol is "mcount" just to keep things
 nice and simple in the examples.
 
@@ -56,8 +60,9 @@ size of the mcount call that is embedded in the function).
 
 For example, if the function foo() calls bar(), when the bar() function calls
 mcount(), the arguments mcount() will pass to the tracer are:
-   "frompc" - the address bar() will use to return to foo()
-   "selfpc" - the address bar() (with mcount() size adjustment)
+
+  - "frompc" - the address bar() will use to return to foo()
+  - "selfpc" - the address bar() (with mcount() size adjustment)
 
 Also keep in mind that this mcount function will be called *a lot*, so
 optimizing for the default case of no tracer will help the smooth running of
@@ -67,39 +72,41 @@ means the code flow should usually be kept linear (i.e. no 
branching in the nop
 case).  This is of course an optimization and not a hard requirement.
 
 Here is some pseudo code that should help (these functions should actually be
-implemented in assembly):
+implemented in assembly)::
 
-void ftrace_stub(void)
-{
-   return;
-}
+   void ftrace_stub(void)
+   {
+   return;
+   }
 
-void mcount(void)
-{
-   /* save any bare state needed in order to do initial checking */
+   void mcount(void)
+   {
+   /* save any bare state needed in order to do initial checking */
 
-   extern void (*ftrace_trace_function)(unsigned long, unsigned long);
-   if (ftrace_trace_function != ftrace_stub)
-   goto do_trace;
+   extern void (*ftrace_trace_function)(unsigned long, unsigned 
long);
+   if (ftrace_trace_function != ftrace_stub)
+   goto do_trace;
 
-   /* restore any bare state */
+   /* restore any bare state */
 
-   return;
+   return;
 
-do_trace:
+   do_trace:
 
-   /* save all state needed by the ABI (see paragraph above) */
+   /* save all state needed by the ABI (see paragraph above) */
 
-   unsigned long frompc = ...;
-   unsigned long selfpc =  - MCOUNT_INSN_SIZE;
-   ftrace_trace_function(frompc, selfpc);
+   unsigned long frompc = ...;
+   unsigned long selfpc =  - MCOUNT_INSN_SIZE;
+   ftrace_trace_function(frompc, selfpc);
 
-   /* restore all state needed by the ABI */
-}
+   /* restore all state needed by the ABI */
+   }
 
 Don't forget to export mcount for modules !
-extern void mcount(void);
-EXPORT_SYMBOL(mcount);
+::
+
+   extern void mcount(void);
+   EXPORT_SYMBOL(mcount);
 
 
 HAVE_FUNCTION_GRAPH_TRACER
@@ -127,38 +134,40 @@ That function will simply call the common 
ftrace_return_to_handler function and
 that will return the original return address with which you can return to the
 original call site.
 
-Here is the updated mcount pseudo code:
-void mcount(void)
-{
-...
-   if (ftrace_trace_function != ftrace_stub)
-   goto do_trace;
-
-+#ifdef CONFIG_FUNCTION_GRAPH_TRACER
-+  extern void (*ftrace_graph_return)(...);
-+  extern void (*ftrace_graph_entry)(...);
-+  if (ftrace_graph_return != ftrace_stub ||
-+  ftrace_graph_entry != ftrace_graph_entry_stub)
-+  

[PATCH 2/3] Documentation: convert trace/ftrace-design.txt to rst format

[changbin . du]

From: Changbin Du 

Signed-off-by: Changbin Du 
---
 .../trace/{ftrace-design.txt => ftrace-design.rst} | 248 +++--
 Documentation/trace/index.rst  |   2 +
 2 files changed, 137 insertions(+), 113 deletions(-)
 rename Documentation/trace/{ftrace-design.txt => ftrace-design.rst} (75%)

diff --git a/Documentation/trace/ftrace-design.txt 
b/Documentation/trace/ftrace-design.rst
similarity index 75%
rename from Documentation/trace/ftrace-design.txt
rename to Documentation/trace/ftrace-design.rst
index a273dd0..0f32a85 100644
--- a/Documentation/trace/ftrace-design.txt
+++ b/Documentation/trace/ftrace-design.rst
@@ -1,6 +1,8 @@
-   function tracer guts
-   
-   By Mike Frysinger
+==
+Function Tracer Design
+==
+
+:Author: Mike Frysinger
 
 Introduction
 
@@ -21,8 +23,8 @@ Prerequisites
 -
 
 Ftrace relies on these features being implemented:
- STACKTRACE_SUPPORT - implement save_stack_trace()
- TRACE_IRQFLAGS_SUPPORT - implement include/asm/irqflags.h
+  - STACKTRACE_SUPPORT - implement save_stack_trace()
+  - TRACE_IRQFLAGS_SUPPORT - implement include/asm/irqflags.h
 
 
 HAVE_FUNCTION_TRACER
@@ -32,9 +34,11 @@ You will need to implement the mcount and the ftrace_stub 
functions.
 
 The exact mcount symbol name will depend on your toolchain.  Some call it
 "mcount", "_mcount", or even "__mcount".  You can probably figure it out by
-running something like:
+running something like::
+
$ echo 'main(){}' | gcc -x c -S -o - - -pg | grep mcount
callmcount
+
 We'll make the assumption below that the symbol is "mcount" just to keep things
 nice and simple in the examples.
 
@@ -56,8 +60,9 @@ size of the mcount call that is embedded in the function).
 
 For example, if the function foo() calls bar(), when the bar() function calls
 mcount(), the arguments mcount() will pass to the tracer are:
-   "frompc" - the address bar() will use to return to foo()
-   "selfpc" - the address bar() (with mcount() size adjustment)
+
+  - "frompc" - the address bar() will use to return to foo()
+  - "selfpc" - the address bar() (with mcount() size adjustment)
 
 Also keep in mind that this mcount function will be called *a lot*, so
 optimizing for the default case of no tracer will help the smooth running of
@@ -67,39 +72,41 @@ means the code flow should usually be kept linear (i.e. no 
branching in the nop
 case).  This is of course an optimization and not a hard requirement.
 
 Here is some pseudo code that should help (these functions should actually be
-implemented in assembly):
+implemented in assembly)::
 
-void ftrace_stub(void)
-{
-   return;
-}
+   void ftrace_stub(void)
+   {
+   return;
+   }
 
-void mcount(void)
-{
-   /* save any bare state needed in order to do initial checking */
+   void mcount(void)
+   {
+   /* save any bare state needed in order to do initial checking */
 
-   extern void (*ftrace_trace_function)(unsigned long, unsigned long);
-   if (ftrace_trace_function != ftrace_stub)
-   goto do_trace;
+   extern void (*ftrace_trace_function)(unsigned long, unsigned 
long);
+   if (ftrace_trace_function != ftrace_stub)
+   goto do_trace;
 
-   /* restore any bare state */
+   /* restore any bare state */
 
-   return;
+   return;
 
-do_trace:
+   do_trace:
 
-   /* save all state needed by the ABI (see paragraph above) */
+   /* save all state needed by the ABI (see paragraph above) */
 
-   unsigned long frompc = ...;
-   unsigned long selfpc =  - MCOUNT_INSN_SIZE;
-   ftrace_trace_function(frompc, selfpc);
+   unsigned long frompc = ...;
+   unsigned long selfpc =  - MCOUNT_INSN_SIZE;
+   ftrace_trace_function(frompc, selfpc);
 
-   /* restore all state needed by the ABI */
-}
+   /* restore all state needed by the ABI */
+   }
 
 Don't forget to export mcount for modules !
-extern void mcount(void);
-EXPORT_SYMBOL(mcount);
+::
+
+   extern void mcount(void);
+   EXPORT_SYMBOL(mcount);
 
 
 HAVE_FUNCTION_GRAPH_TRACER
@@ -127,38 +134,40 @@ That function will simply call the common 
ftrace_return_to_handler function and
 that will return the original return address with which you can return to the
 original call site.
 
-Here is the updated mcount pseudo code:
-void mcount(void)
-{
-...
-   if (ftrace_trace_function != ftrace_stub)
-   goto do_trace;
-
-+#ifdef CONFIG_FUNCTION_GRAPH_TRACER
-+  extern void (*ftrace_graph_return)(...);
-+  extern void (*ftrace_graph_entry)(...);
-+  if (ftrace_graph_return != ftrace_stub ||
-+  ftrace_graph_entry != ftrace_graph_entry_stub)
-+  ftrace_graph_caller();
-+#endif
-
-   /* restore any bare