[PATCH] cpu-supplement: Add ARM BSPs chapter

[Sebastian Huber]

On 26/03/18 10:09, 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.

Could we please eventually decide on a place for BSP documentation.

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