Bug 216185

Summary:	Documentation error in Documentation/trace-cmd/trace-cmd.dat.v7.5.txt
Product:	Tools	Reporter:	Matteo Bertolino (matteo.bertolino)
Component:	Trace-cmd/Kernelshark	Assignee:	Default virtual assignee for Trace-cmd and kernelshark (tools_tracecmd_kernelshark)
Status:	RESOLVED CODE_FIX
Severity:	normal	CC:	rostedt, tstoyanov
Priority:	P1
Hardware:	All
OS:	Linux
Kernel Version:	any	Subsystem:
Regression:	No	Bisected commit-id:
Attachments:	To support my report, in the description I provide two demonstrations. One in the source code, one empirical. This image contains the empirical demonstration.

Description Matteo Bertolino 2022-06-28 12:39:18 UTC

Created attachment 301296 [details]
To support my report, in the description I provide two demonstrations. One in the source code, one empirical. This image contains the empirical demonstration.

- *File*: https://github.com/rostedt/trace-cmd/blob/master/Documentation/trace-cmd/trace-cmd.dat.v7.5.txt

- *Latest commit for this file*: ac3ee689f8c4bfef52d4ff9e97d701fda290a247

- *Error location*: lines 68 to 78 for this commit, namely paragraph "FORMAT OF THE SECTION HEADER". 

- *Error* :

I found an issue in this Doc:

'''
FORMAT OF THE SECTION HEADER
----------------------------
  <2 bytes> unsigned short integer, ID of the section.
  <2 bytes> unsigned short integer, section flags:
    1 = the section is compressed.
  <4 bytes> ID of a string, description of the section.
  <4 bytes> unsigned integer, size of the section in the file.
'''

The error is the last field: "<4 bytes> unsigned integer, size of the section in the file."

This should be, instead:
"<8 bytes> long long unsigned integer, size of the section in the file."


*Demonstration(s)*

- Empirical: first of all, I tried it and I have modified trace-cmd code with strategical prints. I added a section 0 whose size is 28. If I write this size on 4 bytes, subsequent function handle_options() fails, if I write this field on 8 bytes, everything is ok. Please, look at the attachment "empiricalTest.png".


- Demonstration by reading the source code of trace-cmd:
./trace-cmd/lib/trace-cmd/trace-input.c, function “read_section_header” this is the part of trace-cmd code that reads that specific section: 

https://github.com/rostedt/tracecmd/blob/master/lib/trace-cmd/trace-input.c#L1083

Latest commit for this file: 719a0a72c3ee1ac3ca5eeb0ac697f371a9881ba0

As you can see, there are two "read2()" calls, for section ID and flags, then a read4() for the description of the section and finally read8() function is called (and not read4 …) for the size.

Comment 1 Tzvetomir Stoyanov 2022-06-28 12:58:24 UTC

You are right Matteo, the section size is 8 bytes. It was 4 bytes in one of the first versions of this implementation, and looks like the documentation is not updated when the size filed was increased. Nice catch, thanks for reporting that!
Do you want to submit a fix, to align the documentation with the actual file format?

Comment 2 Matteo Bertolino 2022-06-29 08:31:07 UTC

Dear Tzvetomir, 
thanks for your feedback. 
I can do it, should I do it in the form of pull request?

Comment 3 Tzvetomir Stoyanov 2022-06-29 08:40:52 UTC

You have to submit a patch to the linux-trace-devel@vger.kernel.org mailing list, and CC rostedt@goodmis.org. There are detailed instructions here https://github.com/rostedt/trace-cmd/blob/master/CONTRIBUTE

Comment 4 Matteo Bertolino 2022-06-29 09:28:56 UTC

Thanks a lot.
I'll do it this afternoon. 
Bests

Comment 5 Steven Rostedt 2023-06-02 08:12:23 UTC

Fixed by: dacbf23e744f ("trace-cmd: Fix description of a field in trace-cmd.dat.v7.5.txt doc")