[PATCH] cpu-supplement: Add ARM BSPs chapter

[Sebastian Huber]

On 05/06/18 16:28, Joel Sherrill wrote:
> Not sure why I haven't weighed in yet.
>
> On Tue, Jun 5, 2018 at 8:56 AM, Gedare Bloom <gedare at rtems.org 
> <mailto: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.

Yes, I would like to have a single documentation location to get started 
with RTEMS on a particular board.

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

Yes, once we have a location for the BSP documentation we can add TBDs.

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

My original proposal was a "RTEMS Hardware Manual" which contains the 
architecture documentation (CPU Supplement) and the BSPs.

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