[PATCH] cpu-supplement: Add ARM BSPs chapter

[Chris Johns]

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.

Chris