Update Atsam BSP Support

[Chris Johns]

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.

I agree.

>
> 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 
documentation resource?

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

Chris