[PATCH] cpu-supplement: Add ARM BSPs chapter

[Sebastian Huber]

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.