Documentation/trace/events.rst: wrong numbering of sections

Documentation/trace/events.rst: wrong numbering of sections

[Li Xinhai]

This document has below numbering of its sections:

1. Introduction
2. Using Event Tracing
2.1 Via the 'set_event' interface
2.2 Via the 'enable' toggle
2.3 Boot option
3. Defining an event-enabled tracepoint
4. Event formats
5. Event filtering
5.1 Expression syntax
5.2 Setting filters
5.3 Clearing filters
5.3 Subsystem filters
5.4 PID filtering
6. Event triggers
6.1 Expression syntax
6.2 Supported trigger commands
6.3 In-kernel trace event API
6.3.1 Dyamically creating synthetic event definitions
6.3.3 Tracing synthetic events from in-kernel code
6.3.3.1 Tracing a synthetic event all at once
6.3.3.1 Tracing a synthetic event piecewise
6.3.4 Dyamically creating kprobe and kretprobe event definitions
6.3.4 The "dynevent_cmd" low-level API

It seems wrong numbering within 6.3 section. 
or, would it be better to have separated chapter #7, for 'In-kernel trace
event API'? it seems not belong to 'Event triggers'.

Re: Documentation/trace/events.rst: wrong numbering of sections

[Steven Rostedt]

It's best to Cc the maintainers of the file. Nobody reads linux-kernel (it
produces 800 emails a day!). Luckily, I happen to monitor the
linux-trace-devel list (which is mostly for userland tools), otherwise this
email would have been lost to the LKML abyss.

On Fri, 15 May 2020 15:43:43 +0800
"Li Xinhai" <lixinhai.lxh@gmail.com> wrote:

> This document has below numbering of its sections:
> 
> 1. Introduction
> 2. Using Event Tracing
> 2.1 Via the 'set_event' interface
> 2.2 Via the 'enable' toggle
> 2.3 Boot option
> 3. Defining an event-enabled tracepoint
> 4. Event formats
> 5. Event filtering
> 5.1 Expression syntax
> 5.2 Setting filters
> 5.3 Clearing filters
> 5.3 Subsystem filters
> 5.4 PID filtering
> 6. Event triggers
> 6.1 Expression syntax
> 6.2 Supported trigger commands
> 6.3 In-kernel trace event API
> 6.3.1 Dyamically creating synthetic event definitions
> 6.3.3 Tracing synthetic events from in-kernel code
> 6.3.3.1 Tracing a synthetic event all at once
> 6.3.3.1 Tracing a synthetic event piecewise
> 6.3.4 Dyamically creating kprobe and kretprobe event definitions
> 6.3.4 The "dynevent_cmd" low-level API
> 
> It seems wrong numbering within 6.3 section. 
> or, would it be better to have separated chapter #7, for 'In-kernel trace
> event API'? it seems not belong to 'Event triggers'.

Yeah, 6.3.4 (both of them) probably should have been under a new top level
section. (#7).

-- Steve

Re: Documentation/trace/events.rst: wrong numbering of sections

[Tom Zanussi]

Hi,

On Fri, 2020-05-15 at 09:11 -0400, Steven Rostedt wrote:
> It's best to Cc the maintainers of the file. Nobody reads linux-
> kernel (it
> produces 800 emails a day!). Luckily, I happen to monitor the
> linux-trace-devel list (which is mostly for userland tools),
> otherwise this
> email would have been lost to the LKML abyss.
> 
> On Fri, 15 May 2020 15:43:43 +0800
> "Li Xinhai" <lixinhai.lxh@gmail.com> wrote:
> 
> > This document has below numbering of its sections:
> > 
> > 1. Introduction
> > 2. Using Event Tracing
> > 2.1 Via the 'set_event' interface
> > 2.2 Via the 'enable' toggle
> > 2.3 Boot option
> > 3. Defining an event-enabled tracepoint
> > 4. Event formats
> > 5. Event filtering
> > 5.1 Expression syntax
> > 5.2 Setting filters
> > 5.3 Clearing filters
> > 5.3 Subsystem filters
> > 5.4 PID filtering
> > 6. Event triggers
> > 6.1 Expression syntax
> > 6.2 Supported trigger commands
> > 6.3 In-kernel trace event API
> > 6.3.1 Dyamically creating synthetic event definitions
> > 6.3.3 Tracing synthetic events from in-kernel code
> > 6.3.3.1 Tracing a synthetic event all at once
> > 6.3.3.1 Tracing a synthetic event piecewise
> > 6.3.4 Dyamically creating kprobe and kretprobe event definitions
> > 6.3.4 The "dynevent_cmd" low-level API
> > 
> > It seems wrong numbering within 6.3 section. 
> > or, would it be better to have separated chapter #7, for 'In-kernel 
> > trace
> > event API'? it seems not belong to 'Event triggers'.
> 
> Yeah, 6.3.4 (both of them) probably should have been under a new top
> level
> section. (#7).
> 

Yeah, aside from duplicate numbering in a couple of places, it would
make more sense for everything starting from '6.3 In-kernel trace event
API' to be in a section 7.

Would you like to submit a patch for that, Li, or should I?

Thanks,

Tom

> -- Steve

Re: Documentation/trace/events.rst: wrong numbering of sections

[Li Xinhai]

>Hi,
>
>On Fri, 2020-05-15 at 09:11 -0400, Steven Rostedt wrote:
>> It's best to Cc the maintainers of the file. Nobody reads linux-
>> kernel (it
>> produces 800 emails a day!). Luckily, I happen to monitor the
>> linux-trace-devel list (which is mostly for userland tools),
>> otherwise this
>> email would have been lost to the LKML abyss.
>>
>> On Fri, 15 May 2020 15:43:43 +0800
>> "Li Xinhai" <lixinhai.lxh@gmail.com> wrote:
>>
>> > This document has below numbering of its sections:
>> >
>> > 1. Introduction
>> > 2. Using Event Tracing
>> > 2.1 Via the 'set_event' interface
>> > 2.2 Via the 'enable' toggle
>> > 2.3 Boot option
>> > 3. Defining an event-enabled tracepoint
>> > 4. Event formats
>> > 5. Event filtering
>> > 5.1 Expression syntax
>> > 5.2 Setting filters
>> > 5.3 Clearing filters
>> > 5.3 Subsystem filters
>> > 5.4 PID filtering
>> > 6. Event triggers
>> > 6.1 Expression syntax
>> > 6.2 Supported trigger commands
>> > 6.3 In-kernel trace event API
>> > 6.3.1 Dyamically creating synthetic event definitions
>> > 6.3.3 Tracing synthetic events from in-kernel code
>> > 6.3.3.1 Tracing a synthetic event all at once
>> > 6.3.3.1 Tracing a synthetic event piecewise
>> > 6.3.4 Dyamically creating kprobe and kretprobe event definitions
>> > 6.3.4 The "dynevent_cmd" low-level API
>> >
>> > It seems wrong numbering within 6.3 section.
>> > or, would it be better to have separated chapter #7, for 'In-kernel
>> > trace
>> > event API'? it seems not belong to 'Event triggers'.
>>
>> Yeah, 6.3.4 (both of them) probably should have been under a new top
>> level
>> section. (#7).
>>
>
>Yeah, aside from duplicate numbering in a couple of places, it would
>make more sense for everything starting from '6.3 In-kernel trace event
>API' to be in a section 7.
>
>Would you like to submit a patch for that, Li, or should I?
> 
I am not sure the correct organization of these part, you maybe better to fix it, thanks.

>Thanks,
>
>Tom
>
>> -- Steve
>