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 <ged...@rtems.org
<mailto:ged...@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.hu...@embedded-brains.de
PGP : Public key available on request.
Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
