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