[PATCH v2] user/bsps : Add documentation for Beagle

[Chris Johns]

On 20/7/19 4:50 pm, Christian Mauderer wrote:
> On 19/07/2019 20:59, Vijay Kumar Banerjee wrote:
>> On Fri, Jul 19, 2019 at 10:32 PM Christian Mauderer <list at c-mauderer.de
>> <mailto:list at c-mauderer.de>> wrote:
>>
>>     On 19/07/2019 18:21, Gedare Bloom wrote:
>>     > Looks good to me. I'm currently not able to apply it, verify the doc
>>     > build, and push it though. (Workstation issues.)
>>     >
>>
>>     I agree that it looks OK. Thanks from me too for contributing to the
>>     documentation. It's something that most developers don't like to do
>>     therefore it's really great that you wrote that.
>>
>> Always glad to contribute. :) 
>>
>>     I didn't find any bugs in the instructions while reading through it. I
>>     can create a PDF out of it on my Arch Linux machine so I think it should
>>     be OK to merge it.
>>
>>     You have tried quite a bit till you get an overlay working. If you feel
>>     like writing some more documentation, it might would be a good addition
>>     to add some notes regarding that too. I think this patch is fine as it
>>     is so if you add something please create a second patch.
>>
>> Sure, I can write about creating and overlay and applying it to the base
>> tree.
>> What would be the right place to write it? 
> 
> Hard to say. You worked with the Beagle BSP so for now maybe adding an
> example + the command to apply an overlay there wouldn't be wrong.

The rtems-boot-image has support for an FDT blob and I plan to add overlay
support when I get time.

We currently do not cover the FDT source and building blobs and we should if we
want to lower the entry level for someone wanting to pick up RTEMS and an
available piece of hardware like a BBB.

> I don't think there is a special "device tree" chapter right now.

I feel need something. It is part of RTEMS now and we should document how and
where it is used. When I returned to using the BBB I need to figure all this out
and it is not apparent or user friendly. For example initialising libbsd without
an FDT results in a crash.

> Maybe an alternative would be to put a "device tree and overlay" chapter
> into the README in libbsd. I think you as well as Niels are using
> overlays only with libbsd.

I think the user manual is the best place. I think it could live in the
Executables section.

>> I have also wondered if it would be a good idea to keep the overlays in
>> RTEMS
>> or libBSD repo somewhere along with a script that builds a dtb from the
>> freebsd-org
>> tree and applies the overlay. 
> 
> If you want you can create a script for libbsd to build the dtb.

Scripts are OK for development work and personal projects however it creates a
legacy issue for the project. Scripts are often host and shell specific and
while they capture the logic they take a lot of work to useful and a general
solution.

> Although cloning the freebsd-org submodule is optional, it can give a
> good hint how to build a target dtb. If you do that, please create it in
> a way that it's easy to tell which device tree should be build.

I agree cloning FreeBSD as a sub-module is not something we would like to do. We
do need to try and capture this information somehow for a release.

> An alternative could be to just put the hand full of commands in the
> README in libbsd.
> 
> Keeping overlays in libbsd or RTEMS is maybe not that optimal.

I agree.

> Overlays are quite target / application specific.

Are they application specific or specific to the target hardware and the support
RTEMS has for various parts of the hardware?

Does it matter if I have all the possible overlays loaded for the BBB and I do
not to use any of them? I think it is better to do this than attempting to use a
supported driver and finding I am missing the needed FDT support.

> So I'm a bit afraid of a big
> number of poorly maintained files. I would prefer to have only a small
> number of examples for overlays in the README. Other overlays are more
> target specific.

I am not sure I understand the first part and I agree overs are target specific.
For a publicly available piece of hardware like a BBB there must be a known set
of overlays that RTEMS supports? Custom hardware is not our concern.

The rtems-boot-image tool provides a command line interface to the complexity of
creating an SD image on different hosts. Adding overlay FDT support to this tool
can capture the low level u-boot complexity needed to support overlays.

What if I add support to the RSB to fetch and build the FDT blobs from source
for a specific board?

Chris