Assists and Lops documentation

[onkarharsh]

Hi @zeddii ,
We are working towards documenting all our assists and lops that we use during our embedded software stack build process. As part of that, we would like to understand where we can put these rst files. I believe it is time that we start creating enterprise specific assists and lops directories. Your thoughts?

CC: @sivadur @SamPovilus

[onkarharsh]

Also, Is there a way to get the assists help/usage using lopper front end? something like : lopper baremetal_xparameters_xlnx --help

I see the usage prints in here https://github.com/devicetree-org/lopper/blob/master/lopper/assists/extract-xen.py#L31 , How to use this?

[zeddii]

There's a few questions in there, let me try and answer them individually.

• Do we want to have a strict / enforced partitioning on lops and assists by their function: no
• Can we have multiple directories and subdirectories for lops and assists: yes, but by not putting them all in one location we complicate searching, introduce the possibility of name collisions and just make them generally harder to find. I disagree with premature sorting and ordering of them, I don't think we are anywhere near where we need it yet
• If you do have documentation files, they can either go in the documentation directory, or they can just be placed directly in the assist/lop directory. Both have their pros and cons.
• Lopper can already pass along calls directly to the assists, we can use that for any embedded help messages. You currently have to do a chain call though. extract-xen wasn't the best example, since it isn't currently wired up properly (I'll fix that)

Here's a working example:

% ./lopper.py -f device-trees/system-device-tree.dts foo.dts -- compare --help

Usage: compare [OPTION]

  -p       permissive matching on target node (regex)
  -v       enable verbose debug/processing
  -x       exclude nodes or properties
  -o       output directory for files
  -c       run a specific comparision (default is "all")
           current options are: "name"

But I can make that easier, but not requiring both the in and output file and possibly doing automatic chaining to the subcommand. I'll implement that in the next couple of days and use this as the issue to track it

[onkarharsh]

Thanks @zeddii for the response.
Yes, not mandating an input-output file for assist to get the help message would be useful. That helps.

Regarding the multiple directories and sub-directories for lops and assists: I am coming from a point of view that all our assists/lops are very AMD specific. During their documentation, we may have to explicitly mention the output file names and the tools that they are needed for (e.g. Yocto Build system, Vitis build system etc.).

Before starting the work, I just want to check whether we have the consensus that we can put all such docs inside the common lops and assists directory of open source lopper or we should create an AMD specific lops and assists directory and dump all our assists/lops and respective documentations there.

[zeddii]

551a67f

I just need to let this soak for a few days to see if I missed any corner cases on the handling.

[zeddii]

For the documentation/assists question: we had decided early on in lopper's development that we wouldn't sort by company/contributor but instead just use the common directories. That way they can serve as a reference for all users and we can identify if there is missing core functionality or duplication.

I don't have an issue with using the common directories for both, but a first step to see if separating the content causes any issues / confusion we could create an AMD specific documentation directory and do that work there, while leaving the actual lops/assists in a common location.

[onkarharsh]

Thanks for the confirmation @zeddii . We will create a separate doc directory for AMD and leave the existing lops/assists as is. We will soon send the Pull Request for the same. Please feel free to close this Issue once your updates for assists' help is in.