[PATCH] cpu-supplement: Add ARM BSPs chapter

Tue Jun 5 13:56:15 UTC 2018

Hi Sebastian, Joel:

I am unsure about the placement of BSP guidance in the User Manual. I
like the change overall it is positive to create high-quality BSP
documentation.  I have 2 concerns:
1. It should be clearly labelled as an incomplete set of the BSPs
however. Right now, if someone picks up this example user.pdf, it
would seem we have only one BSP in RTEMS if you only look at this new
chapter. Maybe it makes sense to merge the text from 8.3 Board Support
Packages (BSP) into the new chapter dedicated toward BSPs.
2. The size of this Chapter 9 BSPs eventually is going to become much
larger compared to the rest of the manual. It might make better sense
to create it as a supplemental document that you refer to from 8.3
Board Support Packages (BSP). As you say, it is different from the BSP
Developer's Guide, but I think it will be sensible to create an "RTEMS
User Manual BSP Supplement".

Gedare

On Tue, Jun 5, 2018 at 2:52 AM, Sebastian Huber
<sebastian.huber at embedded-brains.de> wrote:
> Ping.
>
>
> On 30/04/18 08:26, Sebastian Huber wrote:
>>
>> On 17/04/18 12:30, Chris Johns wrote:
>>>
>>> On 26/3/18 7:09 pm, Sebastian Huber wrote:
>>>>
>>>> On 26/03/18 00:50, Chris Johns wrote:
>>>>>
>>>>> On 14/03/2018 17:20, Sebastian Huber wrote:
>>>>>>
>>>>>> On 13/03/18 22:58, Chris Johns wrote:
>>>>>>>
>>>>>>> On 09/03/2018 19:55, Sebastian Huber wrote:
>>>>>>>>
>>>>>>>> On 06/11/17 10:03, Sebastian Huber wrote:
>>>>>>>>>
>>>>>>>>> On 26/10/17 08:22, Sebastian Huber wrote:
>>>>>>>>>>
>>>>>>>>>> Please review this patch carefully. It adds a new chapter "ARM
>>>>>>>>>> Board Support
>>>>>>>>>> Packages" following the "ARM Specific Information" chapter. It
>>>>>>>>>> adds a
>>>>>>>>>> template structure for other BSPs.
>>>>>>>>>>
>>>>>>>>>> Where should we place common BSP configuration options like
>>>>>>>>>> BSP_PRESS_KEY_FOR_RESET? We probably don't want to add a copy and
>>>>>>>>>> paste
>>>>>>>>>> version to every BSP section.
>>>>>>>>>>
>>>>>>>>> Any comments with respect to the BSP documentation? It makes little
>>>>>>>>> sense to
>>>>>>>>> start with this work if the general direction is unclear.
>>>>>>>>>
>>>>>>>> The insufficient and user unfriendly BSP documentation is still a
>>>>>>>> big issue
>>>>>>>> from
>>>>>>>> my point of view. I think it is one of be biggest obstacles to get
>>>>>>>> started
>>>>>>>> with
>>>>>>>> RTEMS. The BSP documentation should be part of a sphinx based
>>>>>>>> rtems-docs
>>>>>>>> manual.
>>>>>>>>
>>>>>>> How do we get the large number of BSP_OPTS parameters out of the BSPs
>>>>>>> and into
>>>>>>> suitable documentation? I am reluctant to support fragmented or
>>>>>>> partial
>>>>>>> approaches to solving this problem, I feel the "project" or effect
>>>>>>> needs to
>>>>>>> accept _all_ BSPs need to be covered. This is a community effort that
>>>>>>> needs
>>>>>>> some
>>>>>>> leadership and ownership.
>>>>>>>
>>>>>>> It is a difficult area because:
>>>>>>>
>>>>>>> 1. The overlap to device TRMs and yet wanting to provide some self
>>>>>>> contained
>>>>>>> information for a device knowledgeable user.
>>>>>>>
>>>>>>> 2. How is it maintained and checked? Reviews of patches require
>>>>>>> related doc
>>>>>>> patches?
>>>>>>>
>>>>>>> 3. Changing the build system, the waf build Amar created changes the
>>>>>>> way
>>>>>>> BSP_OPTS are handled requiring clear definition with ranges and other
>>>>>>> factors
>>>>>>> and that could be annotated with suitable documentation allowing
>>>>>>> automatic
>>>>>>> generation. Do we push for funding for this effort and deal with it
>>>>>>> then?
>>>>>>
>>>>>> For BSP documentation you need to know the hardware and the BSP in
>>>>>> detail. I
>>>>>> think we can only do this step by step and should focus on the BSPs
>>>>>> that are
>>>>>> still in use and maintained. We need a clear concept of the desired
>>>>>> BSP
>>>>>> documentation, so that it is easy for new contributors to fix the
>>>>>> documentation
>>>>>> of their BSP of interest. A build configuration command line help for
>>>>>> BSP
>>>>>> options would be nice, but I think this is optional. I would remove
>>>>>> the BSP
>>>>>> options documentation in configure.ac for BSPs which document the
>>>>>> options in a
>>>>>> manual. If we want to provide build configuration command line help,
>>>>>> then we
>>>>>> should generate it from some documentation master and use it for the
>>>>>> command
>>>>>> line help and the manual. This is some extra effort. It is probably in
>>>>>> the range
>>>>>> of several man weeks to update the documentation of all BSPs.
>>>>>
>>>>> Agreed and this will need to change any way. A waf build system would
>>>>> bring all
>>>>> these option out to the top level which is a important. They are hidden
>>>>> at the
>>>>> moment which is painful.
>>>>>
>>>>>> The manual should have one level for the architectures, one level for
>>>>>> the BSPs
>>>>>> and one for the BSP details. I would not use more than three levels in
>>>>>> a PDF
>>>>>> document. Do we want to create a dedicated BSP manual or merge it into
>>>>>> an
>>>>>> existing manual (which one and how)?
>>>>>
>>>>> Can the BSP and Driver Guide be used or do you think we need something
>>>>> new?
>>>>
>>>> The BSP and Driver Guide contains mostly information for a BSP and
>>>> driver
>>>> developer.
>>>>
>>>> If we use four levels, we could add this to the User Manual (it uses
>>>> already
>>>> four levels), e.g.
>>>>
>>>> Board Support Packages (BSPs)
>>>>      -> Architecture
>>>>          -> BSP
>>>>              -> Some stuff
>>>>
>>>> See attached file.
>>>>
>>> The PDF file looks good. I am OK with this but I would like Joel to
>>> respond.
>>
>>
>> Joel, what is your point of view?
>>
>
> --
> Sebastian Huber, embedded brains GmbH
>
> Address : Dornierstr. 4, D-82178 Puchheim, Germany
> Phone   : +49 89 189 47 41-16
> Fax     : +49 89 189 47 41-09
> E-Mail  : sebastian.huber at embedded-brains.de
> PGP     : Public key available on request.
>
> Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel