<div dir="ltr">Not sure why I haven't weighed in yet.<br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, Jun 5, 2018 at 8:56 AM, Gedare Bloom <span dir="ltr"><<a href="mailto:gedare@rtems.org" target="_blank">gedare@rtems.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi Sebastian, Joel:<br>
<br>
I am unsure about the placement of BSP guidance in the User Manual. I<br>
like the change overall it is positive to create high-quality BSP<br>
documentation.  </blockquote><div><br></div><div>Someone mentioned duplicating the TRM for the CPU or board. That's </div><div>a bit unavoidable on a topic level when you have an option which is</div><div>the initial value for a specific IO register or clock. You have to describe</div><div>that option well enough for a user to be able to set it. This will necessarily</div><div>duplicate some information. We can reference the appropriate documentation</div><div>and source files.</div><div><br></div><div>This also applies at a board level when it comes to jumper, DIP switch,</div><div>or ROM monitor settings.</div><div><br></div><div>Since we leave U-Boot mkimage invocation to the user's imagination that's</div><div>another piece of the puzzle which the user needs to know.</div><div><br></div><div>Advice and set up on debug HW or target agents known to work.</div><div><br></div><div>The goal should be that they get all the info they need to configure their</div><div>hardware and RTEMS to match expectations. We don't have to duplicate</div><div>third party manuals but we should give the user a roadmap to get things</div><div>working.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">I have 2 concerns:<br>
1. It should be clearly labelled as an incomplete set of the BSPs<br>
however. Right now, if someone picks up this example user.pdf, it<br>
would seem we have only one BSP in RTEMS if you only look at this new<br>
chapter. Maybe it makes sense to merge the text from 8.3 Board Support<br>
Packages (BSP) into the new chapter dedicated toward BSPs.<br></blockquote><div><br></div><div>One solution to this is to fill in the outline with TBDs for at least all the</div><div>architectures.</div><div><br></div><div>We need to figure out how to deal with BSP variants.</div><div><br></div><div>We also need to assume that core developers will have to write the</div><div>sections on simulator BSPs. I expect a fairly standard template for a</div><div>qemu or gdb based simulator.</div><div><br></div><div>I have wondered if we need a tracking spreadsheet for BSPs to show</div><div>what we think is missing or needs updating. For example, some BSPs</div><div>still don't have the linkcmds sections for per-function linking. Some older</div><div>BSPs are still in use and perhaps by pinging people we can get sections</div><div>filled in. But on the other hand, this could indicate a BSP is on a path to</div><div>deprecation. The lack of documentation is another brick in this wall.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
2. The size of this Chapter 9 BSPs eventually is going to become much<br>
larger compared to the rest of the manual. It might make better sense<br>
to create it as a supplemental document that you refer to from 8.3<br>
Board Support Packages (BSP). As you say, it is different from the BSP<br>
Developer's Guide, but I think it will be sensible to create an "RTEMS<br>
User Manual BSP Supplement".<br></blockquote><div><br></div><div>Depends on the length per BSP family or BSP variant. Five pages per</div><div>variant will end up in the 800-1000 page range. That would be a lovely</div><div>problem to have. </div><div><br></div><div>I hesitate to start another document that is tiny but if we start it with</div><div>a complete outline with TBD sections, it makes sense. It will be fairly</div><div>hefty even with TBDs.</div><div><br></div><div>--joel</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class="HOEnZb"><font color="#888888"><br>
Gedare<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
On Tue, Jun 5, 2018 at 2:52 AM, Sebastian Huber<br>
<<a href="mailto:sebastian.huber@embedded-brains.de">sebastian.huber@embedded-<wbr>brains.de</a>> wrote:<br>
> Ping.<br>
><br>
><br>
> On 30/04/18 08:26, Sebastian Huber wrote:<br>
>><br>
>> On 17/04/18 12:30, Chris Johns wrote:<br>
>>><br>
>>> On 26/3/18 7:09 pm, Sebastian Huber wrote:<br>
>>>><br>
>>>> On 26/03/18 00:50, Chris Johns wrote:<br>
>>>>><br>
>>>>> On 14/03/2018 17:20, Sebastian Huber wrote:<br>
>>>>>><br>
>>>>>> On 13/03/18 22:58, Chris Johns wrote:<br>
>>>>>>><br>
>>>>>>> On 09/03/2018 19:55, Sebastian Huber wrote:<br>
>>>>>>>><br>
>>>>>>>> On 06/11/17 10:03, Sebastian Huber wrote:<br>
>>>>>>>>><br>
>>>>>>>>> On 26/10/17 08:22, Sebastian Huber wrote:<br>
>>>>>>>>>><br>
>>>>>>>>>> Please review this patch carefully. It adds a new chapter "ARM<br>
>>>>>>>>>> Board Support<br>
>>>>>>>>>> Packages" following the "ARM Specific Information" chapter. It<br>
>>>>>>>>>> adds a<br>
>>>>>>>>>> template structure for other BSPs.<br>
>>>>>>>>>><br>
>>>>>>>>>> Where should we place common BSP configuration options like<br>
>>>>>>>>>> BSP_PRESS_KEY_FOR_RESET? We probably don't want to add a copy and<br>
>>>>>>>>>> paste<br>
>>>>>>>>>> version to every BSP section.<br>
>>>>>>>>>><br>
>>>>>>>>> Any comments with respect to the BSP documentation? It makes little<br>
>>>>>>>>> sense to<br>
>>>>>>>>> start with this work if the general direction is unclear.<br>
>>>>>>>>><br>
>>>>>>>> The insufficient and user unfriendly BSP documentation is still a<br>
>>>>>>>> big issue<br>
>>>>>>>> from<br>
>>>>>>>> my point of view. I think it is one of be biggest obstacles to get<br>
>>>>>>>> started<br>
>>>>>>>> with<br>
>>>>>>>> RTEMS. The BSP documentation should be part of a sphinx based<br>
>>>>>>>> rtems-docs<br>
>>>>>>>> manual.<br>
>>>>>>>><br>
>>>>>>> How do we get the large number of BSP_OPTS parameters out of the BSPs<br>
>>>>>>> and into<br>
>>>>>>> suitable documentation? I am reluctant to support fragmented or<br>
>>>>>>> partial<br>
>>>>>>> approaches to solving this problem, I feel the "project" or effect<br>
>>>>>>> needs to<br>
>>>>>>> accept _all_ BSPs need to be covered. This is a community effort that<br>
>>>>>>> needs<br>
>>>>>>> some<br>
>>>>>>> leadership and ownership.<br>
>>>>>>><br>
>>>>>>> It is a difficult area because:<br>
>>>>>>><br>
>>>>>>> 1. The overlap to device TRMs and yet wanting to provide some self<br>
>>>>>>> contained<br>
>>>>>>> information for a device knowledgeable user.<br>
>>>>>>><br>
>>>>>>> 2. How is it maintained and checked? Reviews of patches require<br>
>>>>>>> related doc<br>
>>>>>>> patches?<br>
>>>>>>><br>
>>>>>>> 3. Changing the build system, the waf build Amar created changes the<br>
>>>>>>> way<br>
>>>>>>> BSP_OPTS are handled requiring clear definition with ranges and other<br>
>>>>>>> factors<br>
>>>>>>> and that could be annotated with suitable documentation allowing<br>
>>>>>>> automatic<br>
>>>>>>> generation. Do we push for funding for this effort and deal with it<br>
>>>>>>> then?<br>
>>>>>><br>
>>>>>> For BSP documentation you need to know the hardware and the BSP in<br>
>>>>>> detail. I<br>
>>>>>> think we can only do this step by step and should focus on the BSPs<br>
>>>>>> that are<br>
>>>>>> still in use and maintained. We need a clear concept of the desired<br>
>>>>>> BSP<br>
>>>>>> documentation, so that it is easy for new contributors to fix the<br>
>>>>>> documentation<br>
>>>>>> of their BSP of interest. A build configuration command line help for<br>
>>>>>> BSP<br>
>>>>>> options would be nice, but I think this is optional. I would remove<br>
>>>>>> the BSP<br>
>>>>>> options documentation in <a href="http://configure.ac" rel="noreferrer" target="_blank">configure.ac</a> for BSPs which document the<br>
>>>>>> options in a<br>
>>>>>> manual. If we want to provide build configuration command line help,<br>
>>>>>> then we<br>
>>>>>> should generate it from some documentation master and use it for the<br>
>>>>>> command<br>
>>>>>> line help and the manual. This is some extra effort. It is probably in<br>
>>>>>> the range<br>
>>>>>> of several man weeks to update the documentation of all BSPs.<br>
>>>>><br>
>>>>> Agreed and this will need to change any way. A waf build system would<br>
>>>>> bring all<br>
>>>>> these option out to the top level which is a important. They are hidden<br>
>>>>> at the<br>
>>>>> moment which is painful.<br>
>>>>><br>
>>>>>> The manual should have one level for the architectures, one level for<br>
>>>>>> the BSPs<br>
>>>>>> and one for the BSP details. I would not use more than three levels in<br>
>>>>>> a PDF<br>
>>>>>> document. Do we want to create a dedicated BSP manual or merge it into<br>
>>>>>> an<br>
>>>>>> existing manual (which one and how)?<br>
>>>>><br>
>>>>> Can the BSP and Driver Guide be used or do you think we need something<br>
>>>>> new?<br>
>>>><br>
>>>> The BSP and Driver Guide contains mostly information for a BSP and<br>
>>>> driver<br>
>>>> developer.<br>
>>>><br>
>>>> If we use four levels, we could add this to the User Manual (it uses<br>
>>>> already<br>
>>>> four levels), e.g.<br>
>>>><br>
>>>> Board Support Packages (BSPs)<br>
>>>>      -> Architecture<br>
>>>>          -> BSP<br>
>>>>              -> Some stuff<br>
>>>><br>
>>>> See attached file.<br>
>>>><br>
>>> The PDF file looks good. I am OK with this but I would like Joel to<br>
>>> respond.<br>
>><br>
>><br>
>> Joel, what is your point of view?<br>
>><br>
><br>
> --<br>
> Sebastian Huber, embedded brains GmbH<br>
><br>
> Address : Dornierstr. 4, D-82178 Puchheim, Germany<br>
> Phone   : +49 89 189 47 41-16<br>
> Fax     : +49 89 189 47 41-09<br>
> E-Mail  : <a href="mailto:sebastian.huber@embedded-brains.de">sebastian.huber@embedded-<wbr>brains.de</a><br>
> PGP     : Public key available on request.<br>
><br>
> Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.<br>
><br>
</div></div><div class="HOEnZb"><div class="h5">> ______________________________<wbr>_________________<br>
> devel mailing list<br>
> <a href="mailto:devel@rtems.org">devel@rtems.org</a><br>
> <a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/<wbr>mailman/listinfo/devel</a><br>
</div></div></blockquote></div><br></div></div>