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

[Christian Mauderer]

On 21/07/2019 04:46, Chris Johns wrote:
> 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.

Great.

> 
> 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.
> 

For BBB Vijays patch should be a big step forward. But I agree that a
crash isn't user friendly.

>> 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.

OK for me too.

> 
>>> 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.
> 

In this case it would be more of an example how to build the dtb.
Therfore I suggested to add the commands to the README as an alternative
further below.

>> 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.

Currently cloning FreeBSD is the only possibility to get the correct
device tree files. When experimenting with some alternative sources
(e.g. the Linux device tree export) I noted that most device trees work
to a certain degree but sometimes there are problems. So the only
version that works reliable with libbsd is the one in the matching
FreeBSD commit.

If you want to have them archived in a release, maybe it would be
necessary to import the device tree files into libbsd? But we should
select which files to import. The whole FreeBSD FDT sources are about
25MB in 3000 files.

What speaks against it is the fact that libbsd is not the only subsystem
that is using FDT. There are at least one or two BSPs in core RTEMS that
use a FDT too.

> 
>> 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?

They can be both.

For example the overlay that Vijay wrote for the I2C adaption layer
could be called target specific. It allows to access the RTEMS I2C
system via the FreeBSD API.

But our beagle BSP currently doesn't call the i2c0 init function. That
is done in the application. If the overlay is active but i2c0 isn't
initialized libbsd might try to init peripherals via a i2c bus that is
not there which would lead to error messages. So it could be seen as
application specific too.

I'm really not sure how I would categorize it.

> 
> 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.

See above: It depends. In most use cases the overlays would be no
problem. But in some they could lead to errors.

On system with shared pins it would be possible to have overlays that
try to use pins either for one subsystem in overlay A or for another in
overlay B. In that case they couldn't be enabled at the same time. On
the Beagle that would be for example the on-board HDMI framer versus a
display connected to the extension headers.

We would have to at least distinguish between "board" overlays that
allow to use on board peripherals and "extension" overlays that allow
external peripherals. Board overlays would provide a "run out of the
box" experience for new users. But there still needs to be an easy
option to disable them if someone wants to do something else with the
subsystem.

> 
>> 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.

That's basically the distinction between "board" and "extension" that I
did above. If we take every extension we get a huge amount of overlays.

> 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.

I'm not sure if all evaluation boards only have one set of usable
overlays. It could be quite possible that some share pins for different
peripherals just so they can show what's possible in different applications.

> 
> 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?

That sounds like a great option. But please be aware that for libbsd it
is necessary to keep the FDT sources in sync with the FreeBSD version
used as a base for libbsd. Again: Maybe importing them into libbsd
wouldn't be the worst idea for that.

> 
> Chris
> 

Best regards

Christian