[PATCH] cpu-supplement: Add ARM BSPs chapter

[Sebastian Huber]

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.

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: user.pdf
Type: application/pdf
Size: 356835 bytes
Desc: not available
URL: <http://lists.rtems.org/pipermail/devel/attachments/20180326/362e3e32/attachment-0002.pdf>