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? Chris _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel