Update Atsam BSP Support
chrisj at rtems.org
Thu Dec 15 22:09:45 UTC 2016
On 15/12/2016 17:21, Sebastian Huber wrote:
>>> It would be quite nice if we can write BSP README files in
>>> reStructuredText placed in the Git repository that show up on the wiki.
>> I support using the ReST format.
>> I am not convinced the Wiki is the best place to land this
>> documentation. These READMEs are really good documentation and we need
>> better BSP documentation. Having it included in the release
>> documentation would be nice.
> We already have BSP documentation on the wiki. We have also BSP
> documentation in the README files. What we really need is to document
> things only once for a specific domain and present it to the user where
> it expects the information.
> Using README files in ReST format gives us the opportunity to present
> the same information
> * in the source tree as a simple text file,
> * in the wiki via plug-in, and
> * in a user manual via sphinx.
I do not think the wiki is needed if a manual contains the needed
content and too many places confuses the work flow for users. I also
feel generated doco on a wiki is confusing because users of a wiki
expect to be able to change the content on the wiki and there is no back
flow to the README source.
The rtems-doco.git repo is user focused and not design or implementation
documentation. I see the wiki holding specific use cases for someone
doing a specific thing as a how to.
Joel and stated to me he would like to see more of the wiki content have
related to Quick Start etc moved into the User Manual to strength it and
make it easier for users and I agree. For example who is going to search
the wiki and remove all SIS BSP related issues how it has been removed
from the master branch? The SIS BSP is still in 4.10 and 4.11 so does
removing those references mean users of those versions have lost a
>> Why not add this documentation to the rtems-docs.git repo?
> Why not move the documentation back into the rtems.git repo?
The docs are a boarder set of topics than just the kernel and it
complicates constant integration.
> I think is it very nice if you have the BSP sources and a basic
> documentation in the same directory.
How often do these files change? I suspect infrequently because they
impact on the user if changes are made. The type of information I see
being in the documentation is user focused so it is about configuration
and management of the BSP and this is a contract between the user and
BSP that should not change without careful consideration.
>> Having the BSP doco in the rtems-docs.git repo means we can make and
>> publish the doc formats we support, ie HTML and PDF, because that repo
>> has all the support needed to build the documentation. It is also
>> supported as part of the release procedure.
>> If the desire is to keep this documentation close to the source, which
>> is attractive, and using rtems-docs.git is a good idea then we need to
>> figure out how to handle this.
> I still think that it was not good to move the documentation sources
> into a separate repository.
I do not agree. Documentation is more than just the RTEMS kernel. We
need to cover Eclipse, debugging, tools not in the kernel source tree,
eco-systems, libbsd, applications, building system issues for
applications and pushing these down into the RTEMS kernel source is
confusing for those topics creating unrelated commit churn which then
effects constant integration.
> We have a lot of copy and paste in the
> documentation and duplicated information in the header files and the
> documentation files.
I would hope the amount of user focused documentation in the headers is
small. We need formal documentation for all the APIs we support and I
would like to see us adding examples to each function to show it's usage.
> One option to simplify this would be a XML file
I tolerant XML, I do not love it. Personally I find INI files a simpler
input format to handle when a user needs to maintain it and INI files
are OK in some cases and not great in others. :)
> which defines and documents the RTEMS interfaces (data types, functions,
> defines, macros, etc.) and then use a generator to produce header (maybe
> even with Doxygen comments) files, documentation files and also test cases.
I would prefer the user documentation be user focused and we aim at just
the supported API functions. These are the functions that do not and
cannot change across releases unless there is a documented, considered
and traceable reason. I am fine with internal, implementation and test
case documentation being on a wiki, deoxygen or what ever works best and
More information about the devel