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