[PATCH] cpu-supplement: Add ARM BSPs chapter

[Chris Johns]

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?

Chris