Re: Update Atsam BSP Support

2016-12-15 Thread 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
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: Update Atsam BSP Support

2016-12-14 Thread Sebastian Huber 



On 15/12/16 01:24, Chris Johns wrote:

On 15/12/2016 00:54, Sebastian Huber wrote:

I would like to refresh this topic.

On 05/10/16 16:17, Gedare Bloom wrote:

That makes sense.

On Wed, Oct 5, 2016 at 1:17 AM, Sebastian Huber
  wrote:

>One way to keep this in sync would be to simply write the README of
each BSP
>in a certain format, e.g. trac wiki and then simply include the
content from
>Git in trac. For example via a modified variant of
>
>https://trac.edgewall.org/attachment/wiki/MacroBazaar/Include.3.py
>
>
>Something like this in trac:
>
>[[RTEMSGitInclude(c/src/lib/libbsp/arm/atsam/README)]]
>


Would it be possible to add such a Trac add-on? I guess I can modify it
so that it works for our purpose, but I don't know how to install it.


Lets see if this is the way we should go before we head down this 
path. Any support added needs to be secure and this simple issue 
complicates what we can or should use in Trac.


Yes.





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.



Why not add this documentation to the rtems-docs.git repo?


Why not move the documentation back into the rtems.git repo?

I think is it very nice if you have the BSP sources and a basic 
documentation in the same directory.




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. We have a lot of copy and paste in the 
documentation and duplicated information in the header files and the 
documentation files. One option to simplify this would be a XML file 
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.


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

Re: Update Atsam BSP Support

2016-12-14 Thread Chris Johns 

On 15/12/2016 00:54, Sebastian Huber wrote:

I would like to refresh this topic.

On 05/10/16 16:17, Gedare Bloom wrote:

That makes sense.

On Wed, Oct 5, 2016 at 1:17 AM, Sebastian Huber
  wrote:

>One way to keep this in sync would be to simply write the README of
each BSP
>in a certain format, e.g. trac wiki and then simply include the
content from
>Git in trac. For example via a modified variant of
>
>https://trac.edgewall.org/attachment/wiki/MacroBazaar/Include.3.py
>
>
>Something like this in trac:
>
>[[RTEMSGitInclude(c/src/lib/libbsp/arm/atsam/README)]]
>


Would it be possible to add such a Trac add-on? I guess I can modify it
so that it works for our purpose, but I don't know how to install it.


Lets see if this is the way we should go before we head down this path. 
Any support added needs to be secure and this simple issue complicates 
what we can or should use in Trac.




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.


Why not add this documentation to the rtems-docs.git repo?

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.


Chris
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: Update Atsam BSP Support

2016-12-14 Thread Sebastian Huber 

I would like to refresh this topic.

On 05/10/16 16:17, Gedare Bloom wrote:

That makes sense.

On Wed, Oct 5, 2016 at 1:17 AM, Sebastian Huber
  wrote:

>One way to keep this in sync would be to simply write the README of each BSP
>in a certain format, e.g. trac wiki and then simply include the content from
>Git in trac. For example via a modified variant of
>
>https://trac.edgewall.org/attachment/wiki/MacroBazaar/Include.3.py
>
>
>Something like this in trac:
>
>[[RTEMSGitInclude(c/src/lib/libbsp/arm/atsam/README)]]
>


Would it be possible to add such a Trac add-on? I guess I can modify it 
so that it works for our purpose, but I don't know how to install it.


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.


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

Re: Update Atsam BSP Support

2016-10-05 Thread Gedare Bloom 
That makes sense.

On Wed, Oct 5, 2016 at 1:17 AM, Sebastian Huber
 wrote:
> One way to keep this in sync would be to simply write the README of each BSP
> in a certain format, e.g. trac wiki and then simply include the content from
> Git in trac. For example via a modified variant of
>
> https://trac.edgewall.org/attachment/wiki/MacroBazaar/Include.3.py
>
>
> Something like this in trac:
>
> [[RTEMSGitInclude(c/src/lib/libbsp/arm/atsam/README)]]
>
>
> On 04/10/16 21:41, Pavel Pisa wrote:
>>
>> Hello Gedare and Alexander,
>>
>> one possible solution to keep that in sync.
>>
>> Change of README in BSP directory
>> to MarkDown or Rest-Text syntax and put on the web
>> generated pages synced directly from master and last stable.
>>
>> On the other hand, wiki allows to include more information
>> and relation links.
>>
>> Best wishes,
>>
>>  Pavel
>>
>> On Tuesday 04 of October 2016 15:21:46 Gedare Bloom wrote:
>>>
>>> Thanks. does this BSP have a wiki page? If not, it would be good to
>>> make one for it. Generally we need to do a better job of keeping a
>>> web-visible "feature set" up to date.
>>>
>>> On Tue, Oct 4, 2016 at 7:39 AM, Alexander Krutwig
>>>
>>>  wrote:

 Hello,

 over the last months, lots of work and effort has been put into the
 development
 of the BSP support for ATSAMV7 microcontrollers by Atmel.
 Thus, I updated the README of the BSP with the work already done in the
 process and
 attached it to this email in order to keep you updated about the
 progress.

 In addition to the work described in the document, we currently work on
 USB and SD-card
 support. Support for NOR flashes is already finished, however, not yet
 committed.

 Best regards,
 Alexander Krutwig

 --
 
 embedded brains GmbH
 Alexander Krutwig
 Dornierstr. 4
 D-82178 Puchheim
 Germany
 email: alexander.krut...@embedded-brains.de
 Phone: +49-89-18 94 741 - 17
 Fax:   +49-89-18 94 741 - 09
 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
>>>
>>> ___
>>> devel mailing list
>>> devel@rtems.org
>>> http://lists.rtems.org/mailman/listinfo/devel
>>
>> ___
>> devel mailing list
>> devel@rtems.org
>> http://lists.rtems.org/mailman/listinfo/devel
>
>
> --
> 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
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: Update Atsam BSP Support

2016-10-04 Thread Sebastian Huber 
One way to keep this in sync would be to simply write the README of each 
BSP in a certain format, e.g. trac wiki and then simply include the 
content from Git in trac. For example via a modified variant of


https://trac.edgewall.org/attachment/wiki/MacroBazaar/Include.3.py


Something like this in trac:

[[RTEMSGitInclude(c/src/lib/libbsp/arm/atsam/README)]]

On 04/10/16 21:41, Pavel Pisa wrote:

Hello Gedare and Alexander,

one possible solution to keep that in sync.

Change of README in BSP directory
to MarkDown or Rest-Text syntax and put on the web
generated pages synced directly from master and last stable.

On the other hand, wiki allows to include more information
and relation links.

Best wishes,

 Pavel

On Tuesday 04 of October 2016 15:21:46 Gedare Bloom wrote:

Thanks. does this BSP have a wiki page? If not, it would be good to
make one for it. Generally we need to do a better job of keeping a
web-visible "feature set" up to date.

On Tue, Oct 4, 2016 at 7:39 AM, Alexander Krutwig

 wrote:

Hello,

over the last months, lots of work and effort has been put into the
development
of the BSP support for ATSAMV7 microcontrollers by Atmel.
Thus, I updated the README of the BSP with the work already done in the
process and
attached it to this email in order to keep you updated about the
progress.

In addition to the work described in the document, we currently work on
USB and SD-card
support. Support for NOR flashes is already finished, however, not yet
committed.

Best regards,
Alexander Krutwig

--

embedded brains GmbH
Alexander Krutwig
Dornierstr. 4
D-82178 Puchheim
Germany
email: alexander.krut...@embedded-brains.de
Phone: +49-89-18 94 741 - 17
Fax:   +49-89-18 94 741 - 09
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

___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel


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

Re: Update Atsam BSP Support

2016-10-04 Thread Pavel Pisa 
Hello Gedare and Alexander,

one possible solution to keep that in sync.

Change of README in BSP directory
to MarkDown or Rest-Text syntax and put on the web
generated pages synced directly from master and last stable.

On the other hand, wiki allows to include more information
and relation links.

Best wishes,

Pavel

On Tuesday 04 of October 2016 15:21:46 Gedare Bloom wrote:
> Thanks. does this BSP have a wiki page? If not, it would be good to
> make one for it. Generally we need to do a better job of keeping a
> web-visible "feature set" up to date.
>
> On Tue, Oct 4, 2016 at 7:39 AM, Alexander Krutwig
>
>  wrote:
> > Hello,
> >
> > over the last months, lots of work and effort has been put into the
> > development
> > of the BSP support for ATSAMV7 microcontrollers by Atmel.
> > Thus, I updated the README of the BSP with the work already done in the
> > process and
> > attached it to this email in order to keep you updated about the
> > progress.
> >
> > In addition to the work described in the document, we currently work on
> > USB and SD-card
> > support. Support for NOR flashes is already finished, however, not yet
> > committed.
> >
> > Best regards,
> > Alexander Krutwig
> >
> > --
> > 
> > embedded brains GmbH
> > Alexander Krutwig
> > Dornierstr. 4
> > D-82178 Puchheim
> > Germany
> > email: alexander.krut...@embedded-brains.de
> > Phone: +49-89-18 94 741 - 17
> > Fax:   +49-89-18 94 741 - 09
> > 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
>
> ___
> devel mailing list
> devel@rtems.org
> http://lists.rtems.org/mailman/listinfo/devel

___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: Update Atsam BSP Support

2016-10-04 Thread Gedare Bloom 
Thanks. does this BSP have a wiki page? If not, it would be good to
make one for it. Generally we need to do a better job of keeping a
web-visible "feature set" up to date.

On Tue, Oct 4, 2016 at 7:39 AM, Alexander Krutwig
 wrote:
> Hello,
>
> over the last months, lots of work and effort has been put into the
> development
> of the BSP support for ATSAMV7 microcontrollers by Atmel.
> Thus, I updated the README of the BSP with the work already done in the
> process and
> attached it to this email in order to keep you updated about the progress.
>
> In addition to the work described in the document, we currently work on USB
> and SD-card
> support. Support for NOR flashes is already finished, however, not yet
> committed.
>
> Best regards,
> Alexander Krutwig
>
> --
> 
> embedded brains GmbH
> Alexander Krutwig
> Dornierstr. 4
> D-82178 Puchheim
> Germany
> email: alexander.krut...@embedded-brains.de
> Phone: +49-89-18 94 741 - 17
> Fax:   +49-89-18 94 741 - 09
> 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
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Update Atsam BSP Support

2016-10-04 Thread Alexander Krutwig 

Hello,

over the last months, lots of work and effort has been put into the 
development

of the BSP support for ATSAMV7 microcontrollers by Atmel.
Thus, I updated the README of the BSP with the work already done in the 
process and

attached it to this email in order to keep you updated about the progress.

In addition to the work described in the document, we currently work on 
USB and SD-card
support. Support for NOR flashes is already finished, however, not yet 
committed.


Best regards,
Alexander Krutwig

--

embedded brains GmbH
Alexander Krutwig
Dornierstr. 4
D-82178 Puchheim
Germany
email: alexander.krut...@embedded-brains.de
Phone: +49-89-18 94 741 - 17
Fax:   +49-89-18 94 741 - 09
PGP: Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.

= Board support package for the Atmel SAM V71/V70/E70/S70 chip platform.
:toc:

== General Information

The BSP is customized to a particular board/chip variant by means of configure
command line options.

Use --enable-chip=XYZ to select the chip variant where XYZ is one of same70j19,
same70j20, same70j21, same70n19, same70n20, same70n21, same70q19, same70q20,
same70q21, sams70j19, sams70j20, sams70j21, sams70n19, sams70n20, sams70n21,
sams70q19, sams70q20, sams70q21, samv71j19, samv71j20, samv71j21, samv71n19,
samv71n20, samv71n21, samv71q19, samv71q20 and samv71q21.  By default the BSP
uses the ATSAMV71Q21 chip.  Not all variants are tested.

Use --enable-sdram=XYZ to select the SDRAM variant where XYZ is one of
is42s16100e-7bli and is42s16320f-7bl. Not all variants are tested with all
controller and speed combinations.

Use BOARD_MAINOSC=XYZ to set the main oscillator frequency in Hz (default
12MHz).

Use BOARD_MCK=XYZ to set the Master Clock (MCK) frequency in Hz (default
123MHz).  The default value enables operation of an external SDRAM, e.g. 150MHz
would be too fast.

Use ATSAM_CONSOLE_BAUD=XYZ to set the initial baud for console devices (default
115200).

Use ATSAM_CONSOLE_DEVICE_TYPE=XYZ to set the device type for /dev/console, use
0 for USART and 1 for UART (default USART).

Use ATSAM_CONSOLE_DEVICE_INDEX=XYZ to set the device index for /dev/console
(default 1, e.g. USART1).

Use ATSAM_CONSOLE_USE_INTERRUPTS=XYZ to set the use interrupt driven mode for
console devices (used by default).

Use ATSAM_MEMORY_TCM_SIZE=XYZ to set the size of tightly coupled memories (TCM)
in bytes (default 0x).

Use ATSAM_MEMORY_INTFLASH_SIZE=XYZ to set the size of internal flash in bytes
(default is derived from chip variant).

Use ATSAM_MEMORY_INTSRAM_SIZE=XYZ to set the size of internal SRAM in bytes
(default is derived from chip variant).

Use ATSAM_MEMORY_SDRAM_SIZE=XYZ to set the size of external SDRAM in bytes
(default 0x0020).

Use ATSAM_MEMORY_QSPIFLASH_SIZE=XYZ to set the size of QSPI flash in bytes
(default 0x0020).

The pins may be configured by the application at link-time.
See link:include/pin-config.h[]

The clock driver uses the ARMv7-M Systick.

The console driver supports the USART and UART devices.

The default linker command file places the code into the internal flash.  Use
"LDFLAGS += -qnolinkcmds -T linkcmds.sdram" to place the code into the external
SDRAM.  Use "LDFLAGS += -qnolinkcmds -T linkcmds.intsram" to place the code
into the internal SRAM.

The fast text section uses the ITCM.  The fast data section uses the DTCM.

Data and instruction cache are enabled during system start.  The RTEMS cache
manager is supported with exception of the freeze functions.

== I2C driver ==

The I2C driver has been realized using the RTEMS I2C framework as a basis.
In order to start communication via I2C, the following steps have to be
executed.

 atsam_register_i2c_0();
 i2c_dev_register_eeprom(
ATSAM_I2C_0_BUS_PATH,
_path[0],
EEPROM_ADDR,
1,
EEPROM_PAGE_SIZE,
size_in_bytes,
0
);

Now, the device can be opened via the open command.

 int fd_in;
 int fd_out;
 fd_in = open(_path[0], O_RDWR);
 fd_out = open(_path[0], O_RDWR);

From now on, normal read and writes can be executed using the I2C device.

 ssize_t read_bytes;
 uint8_t data_in[EEPROM_SIZE];
 n = read(fd_in, _in[0], EEPROM_SIZE);

After completion, the bus and EEPROM shall be unlinked.

 unlink(ATSAM_I2C_0_BUS_PATH);
 unlink(_path[0]);

== Low-Power Support ==

With the low-power-support, module peripherals can be switched on or off.
Additionally, a timer can be set to wake up from low power mode.
Therefore, a structure called atsam_power_control shall be set. This structure
contains a function pointer where a specific handler can be inserted as well as
a function argument.

As function pointer, the following defines can be used:

 ATSAM_POWER_PERIPHERAL(switch on or off certain peripheral)
 ATSAM_POWER_CLOCK_DRIVER(switches off clock interrupts)
 ATSAM_POWER_SLEEP_MODE(enters processor sleep mode)
 ATSAM_POWER_RTC_DRIVER(a)(sets a wakeup timer which shall be set in