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

[Chris Johns]

On 21/7/19 6:09 pm, Christian Mauderer wrote:
> 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.

Yes the doc patch is an excellent start. I will be updating this section once my
BBB libdebugger patch is posted and merged. It needs a hardware mod to work. I
was waiting for testing feedback.

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

Great.

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

Please do this. I was not meaning to say it is one or the other, it was more a
case of not overreaching and keeping in mind we need to look at and work towards
supported solutions. I am pushing hard to streamline our BSP support and using
the BBB as the lead example of what we can do and aim for. My recent BSP build
patches for the RSB are an example.

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

This makes sense. It also means it is harder for a user to know they have a
suitable and working match for the libbsd we provide.

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

I can see sys/dts. Are there more trees?

I was not thinking about all the sources, I was wondering about just the ones a
BSP needs. It may mean we need to have 10, 20 or more sources in an RSB config.
My recent RSB patch to add libbsd fixes the version so this would help but this
is still awkward, for example switching between `master` and the `rtems5` branch
in libbsd.

I am also OK with us adding all the FTS source to our repo. If it is what we
need and we cannot find a cleaner solution I suppose we need to consider this.
It is 25M however a full BBB BSP build is 1.4G installed!

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

Hmm that is awkward. I see altera-cyclone-v hints at FDT in the boot loader
command but I cannot see anything about the FDT source, blobs, or handling. Same
with qoriq. I cannot see any other references in the doco. Without further
information or support being added I have to assume the users understand what is
needed. I suggest we focus on FreeBSD and the BSPs support in RTEMS be a special
case?

There is also the implied steps of a suitable U-boot and mkimage being available
and all this being brought together in a suitable way on a target. For example
an update of libbsd breaks an existing boot loader set up a user.

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

Agreed.

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

Is this a feature of the current state of development of the BBB I2C support? :)

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

I am not across the current libbsd initialise details to offer a solution. It
would be nice to have libbsd handle the init call. I am ok with the various I2C
devices being probed and handled by LibBSD even it a user does not directly use
them. This implies always needing the I2C overlay. I feel having fewer options
or variation is simpler in the long run.

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

Are these errors or bugs? :)

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

Oh that is a really good point.

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

Yes this is what I was thinking but did not know how to express. Thank you.

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

Ah ok and yes we need to provide the basics and the way to make changes.

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

OK.

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

Yeah I am starting to think this is the case. If placed in libbsd I would update
it's build system to build what we need. Without this I would be concern about
switch branches.

It is not a complete end to end solution but I think it is an important step.

Chris