[PATCH] cpu-supplement: Add ARM BSPs chapter

[Chris Johns]

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?

Chris