[PATCH] cpu-supplement: Add ARM BSPs chapter

[Sebastian Huber]

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.

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)?

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