LTTng sched_switch documentation patch.

[Sebastian Huber]

On 27/08/2019 02:43, Chris Johns wrote:
> On 26/8/19 8:16 pm, Ravindra Kumar Meena wrote:
>> Hello Chris and Sebastian,
>>
>> I have attached the updated LTTng sched_switch documentation patch(v4). This one
>> is a whole single patch.
>>
>> *What changed v3 to v4:*
>> Sebastian's patch for rtems-libbsd patch got merged today, So I have removed my
>> GitHub repo link from the documentation and updated it. There are some minor
>> changes like whitespace fixes etc.
>>
>> Please review the patch.
> 
> Steps [1-5] ... Why not use the REST list numbering rather than inventing
> something? This is for 10.5.1 Trace Compass and 10.5.2.
> 
> 10.5.1 Trace Compass
> 
> Step 1:
> 
> This is specific to QEMU and that leaves me wondering if this method of trace
> works on all targets.
> 
> The language is not specific. For example "The host can be connected to target
> via telnet." for what purpose and why? The documentation does not provide me
> with any direction.

Mentioning Telnet in this section is completely superfluous. The record 
tracing is not related to Telnet.

> 
> 10.5.2 RTEMS LTTng Trace Generation Example
> 
> Step 1:
> 
> I think the language is too casual, for example ...
> 
> "Step 1: Clone the repositories rtems-libbsd and rtems-tools and set up the
> environment, if haven’t done already."
> 
> This should reference the specific sections in the User manual that detail how
> to do this.

A section for rtems-libbsd doesn't exist yet. The tools should ship via 
the RSB. I have to update RSB to pick up the latest tools.

> 
> Step 3:
> 
> Can the `Host` box be expanded to show how each of the other parts are connected?
> 
> Step 2:
> 
> I feel we should reference the rtems-run command to run these qemu sessions. If
> there needs to be extra detail that handles the net connection then this should
> be investigated and added to `rtems-run`.

Yes, but this requires some extra work and this GSoC project is 
finished. Maybe we should add a note that this is a TODO.

> 
> Step 3:
> 
> This does not specify the host these command are to be used on. If this is Linux
> are these command available on all distros? It is complicated to make a
> cross-platform way to handle this but this is what needs to be solved for RTEMS.
> I am not sure what is needed but I suspect we may need a tool in rtems-tools to
> wrap the cross-platform ways of doing this.
> 
> Telnet is not available on MacOS any more. This has been discussed on this list
> before. The issue is the User Manual is for all hosts and we need to consider
> and cater for a new user who uses MacOS. There is no indication of why this is
> needed to use this method of trace.

Telnet is not needed. You can get the raw record stream via

https://www.freebsd.org/cgi/man.cgi?nc

https://linux.die.net/man/1/nc

> 
> The reason I raise these things is a core developer would need to clean this up. >
> Step 4:
> 
> I raised using commands in the build before now. Please do not do this. A user
> will not built the rtems-tool repo by hand and will not have a `build`
> directory. The RSB will build and install the tools.

Yes, the tools should ship via RSB.

> 
> What is `raw-data`? There is no explanation of the types of data, where they
> come from and what uses them.

Yes, this needs to be better explained.

> 
> Step 5:
> 
> Maybe it would be good to present more detail on what is needed to install Trace
> Compass. This could be in the Trace Compass section. Has anyone promoting this
> method of trace actually tried FreeBSD and solved how this is done? I hope this
> is not being left to a FreeBSD user to sort out.
> 
> I followed the link and see MacOS, Linux, and Windows. Also I think the Add-On
> link is too specific and maybe fragile. An RTEMS release will capture this link
> and it needs to be around for a number of years.

I think we should not duplicate Trace Compass documentation here. A link 
to the project page should be enough. I would also not mention the Trace 
Compass tutorial.

I don't have a FreeBSD machine with a graphical user interface.

> 
> Step 6:
> 
> I see no value in the screen capture. It is impossible to see any detail and
> there is no context explaining any parts of interest. I can see what the tool
> does on the Trace Compass website.

Yes, using Trace Compass is out of scope.

> 
> "Move the trace and metadata generated in common folder ..." ? What is this?

Yes, this needs to be better explained.

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.