[PATCH] cpu-supplement: Add ARM BSPs chapter

Tue Jun 5 14:28:57 UTC 2018

Not sure why I haven't weighed in yet.

On Tue, Jun 5, 2018 at 8:56 AM, Gedare Bloom <gedare at rtems.org> wrote:

> Hi Sebastian, Joel:
>
> I am unsure about the placement of BSP guidance in the User Manual. I
> like the change overall it is positive to create high-quality BSP
> documentation.

Someone mentioned duplicating the TRM for the CPU or board. That's
a bit unavoidable on a topic level when you have an option which is
the initial value for a specific IO register or clock. You have to describe
that option well enough for a user to be able to set it. This will
necessarily
duplicate some information. We can reference the appropriate documentation
and source files.

This also applies at a board level when it comes to jumper, DIP switch,
or ROM monitor settings.

Since we leave U-Boot mkimage invocation to the user's imagination that's
another piece of the puzzle which the user needs to know.

Advice and set up on debug HW or target agents known to work.

The goal should be that they get all the info they need to configure their
hardware and RTEMS to match expectations. We don't have to duplicate
third party manuals but we should give the user a roadmap to get things
working.

> I have 2 concerns:
> 1. It should be clearly labelled as an incomplete set of the BSPs
> however. Right now, if someone picks up this example user.pdf, it
> would seem we have only one BSP in RTEMS if you only look at this new
> chapter. Maybe it makes sense to merge the text from 8.3 Board Support
> Packages (BSP) into the new chapter dedicated toward BSPs.
>

One solution to this is to fill in the outline with TBDs for at least all
the
architectures.

We need to figure out how to deal with BSP variants.

We also need to assume that core developers will have to write the
sections on simulator BSPs. I expect a fairly standard template for a
qemu or gdb based simulator.

I have wondered if we need a tracking spreadsheet for BSPs to show
what we think is missing or needs updating. For example, some BSPs
still don't have the linkcmds sections for per-function linking. Some older
BSPs are still in use and perhaps by pinging people we can get sections
filled in. But on the other hand, this could indicate a BSP is on a path to
deprecation. The lack of documentation is another brick in this wall.

> 2. The size of this Chapter 9 BSPs eventually is going to become much
> larger compared to the rest of the manual. It might make better sense
> to create it as a supplemental document that you refer to from 8.3
> Board Support Packages (BSP). As you say, it is different from the BSP
> Developer's Guide, but I think it will be sensible to create an "RTEMS
> User Manual BSP Supplement".
>

Depends on the length per BSP family or BSP variant. Five pages per
variant will end up in the 800-1000 page range. That would be a lovely
problem to have.

I hesitate to start another document that is tiny but if we start it with
a complete outline with TBD sections, it makes sense. It will be fairly
hefty even with TBDs.

--joel

>
> Gedare
>
> On Tue, Jun 5, 2018 at 2:52 AM, Sebastian Huber
> <sebastian.huber at embedded-brains.de> wrote:
> > 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.
> >
> > _______________________________________________
> > devel mailing list
> > devel at rtems.org
> > http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20180605/bc2b36d5/attachment-0002.html>