[PATCH] cpu-supplement: Add ARM BSPs chapter

[Sebastian Huber]

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.