Re: RSB documentation

[Chris Johns]

On 17/1/19 7:15 pm, Sebastian Huber wrote:
> 
> With respect to an example RTEMS application. Should we
> 
> (1) suggest to check out the examples repository and start from here, or
> 
> (2) should we provide a very simple Makefile based project?
> 
> I tend to option (2) and just mention that the examples repository exists.
> 

This is a complicated problem to solve because of the ABI related issues and the
need for specific flags for each BSP. If you provide explicit values they will
be right for some and wrong for others.

I think we need a section on this topic and we provide the support for build
systems users are willing to submit and support however we need to consider
tools to help this happen.

The long term plan is to provide a command called 'rtems-config' in rtems-tools
that it like pkgconfig. You query it for the flags you need. It is basically the
internals of rtems_waf but brought out to be a specific command. This can then
be used to create a simple Makefile based application we know will work for all
BSPs and architectures.

After the kernel we have 3rd party packages such as libbsd and libdl so we need
to consider how we expand what we support. With this in mind I have recently
been adding support to rtems_waf ...

 https://git.rtems.org/chrisj/rtems_waf.git/?h=libbsd-libdl

This should not be just about waf and rtems_waf, all solutions should be built
on a common framework that encapsulates the RTEMS complexity.

We need to be careful with these examples because users will copy what we do and
this means what we do becomes copied and magnified.

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

Re: RSB documentation

[Sebastian Huber]

On 17/01/2019 07:36, Chris Johns wrote:

On 17/1/19 5:19 pm, Sebastian Huber wrote:

On 17/01/2019 06:45, Chris Johns wrote:

On 14/1/19 5:36 pm, Sebastian Huber wrote:

I added a build of the partially restructured user manual here:

https://ftp.rtems.org/pub/rtems/people/sebh/user.pdf


Any HTML?

https://ftp.rtems.org/pub/rtems/people/sebh/user/index.html


Looks good. I like the arrangement and flow.



Thanks for the review, I checked in the patches. I will now continue to 
work on the Quick Start chapter.


With respect to an example RTEMS application. Should we

(1) suggest to check out the examples repository and start from here, or

(2) should we provide a very simple Makefile based project?

I tend to option (2) and just mention that the examples repository exists.

--
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: RSB documentation

[Chris Johns]

On 17/1/19 5:19 pm, Sebastian Huber wrote:
> On 17/01/2019 06:45, Chris Johns wrote:
>> On 14/1/19 5:36 pm, Sebastian Huber wrote:
>>> I added a build of the partially restructured user manual here:
>>>
>>> https://ftp.rtems.org/pub/rtems/people/sebh/user.pdf
>>>
>> Any HTML?
> 
> https://ftp.rtems.org/pub/rtems/people/sebh/user/index.html
> 

Looks good. I like the arrangement and flow.

>>
>> As an aside in the copyright block I wrote of lot of initial parts of this
>> manual and then have been adding pieces most years including 2018. How do the
>> year lists work?
>>
> 
> It is the same format as in the new licence header of RTEMS:
> 
> https://git.rtems.org/rtems/tree/LICENSE.BSD-2-Clause
> 

Thanks.

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

Re: RSB documentation

[Sebastian Huber]

On 17/01/2019 06:45, Chris Johns wrote:

Do we want to use "tool chain" or "tool set" or "tools" for the RTEMS things
running on the host computer?

Yeah good question. A "tool chain" seems to have a meaning, a compile etc, a
"tool set" is an RSB based term and "tools" is overloaded with the rtems-tools.

I suppose to have a host tool suite? For example, the first sentence from the
Installation section:

  "This section details how to set up and install the RTEMS Ecosystem.
   You will create a tools suite for your host compiler and an RTEMS kernel
   for your selected Board Support Package (BSP)."



Good, "tool suite" for everything in the RTEMS area which runs on the 
host sounds nice.


--
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: RSB documentation

[Sebastian Huber]

On 17/01/2019 06:45, Chris Johns wrote:

On 14/1/19 5:36 pm, Sebastian Huber wrote:

I added a build of the partially restructured user manual here:

https://ftp.rtems.org/pub/rtems/people/sebh/user.pdf


Any HTML?


https://ftp.rtems.org/pub/rtems/people/sebh/user/index.html



As an aside in the copyright block I wrote of lot of initial parts of this
manual and then have been adding pieces most years including 2018. How do the
year lists work?



It is the same format as in the new licence header of RTEMS:

https://git.rtems.org/rtems/tree/LICENSE.BSD-2-Clause

--
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: RSB documentation

[Chris Johns]

On 14/1/19 5:36 pm, Sebastian Huber wrote:
> I added a build of the partially restructured user manual here:
> 
> https://ftp.rtems.org/pub/rtems/people/sebh/user.pdf
> 

Any HTML?

As an aside in the copyright block I wrote of lot of initial parts of this
manual and then have been adding pieces most years including 2018. How do the
year lists work?

> On 13/01/2019 23:03, Chris Johns wrote:
>> On 11/1/19 8:13 pm, Sebastian Huber wrote:
>>> At which position in the manual should it be placed? I think we should
>>> organize the chapters according to the relevance for new users and how the
>>> are used later during application development. I would use the RSB chapter 
>>> as
>>> a reference chapter containing all the details and cover the common case in
>>> the Quick Start chapter. So, I would move the RSB chapter to the end after
>>> the Host Tools.
>> The place the RSB moves to could depend on where some others get moved too. A
>> review of the sections follows.
>>
>> Do we need a "How to use this manual?" section in the Introduction? It could
>> also have a "What to read before starting" part.
> 
> I think this should go into Introduction -> Overview.
> 

Yes I agree and also each major section should have something.

>>
>> The manual is organised as:
>>
>>   Introduction
>>    Overview, features, what a real-time and what a real-time kernel is.
>>
>>   Ecosystem
>>    Rational, open source and deployment. This is to explain what we
>>    call the host side tools, commands, and configuration. Maybe we
>>    need to explain RTEMS is only run on targets and is not self
>>    hosting so the ecosystem provides a consistent host side
>>    environment.
>>
>>    This section needs to be enhanced to cover the RSB, RTEMS Tools
>>    and what ever else we want to include. The deployment section's
>>    building binary tools can be moved to some where else, that is
>>    an advanced topic.
> 
> I moved the Ecosystem into Introduction, since it introduces the RTEMS world. 
> I
> think it fits quite well here.

Nice and yes I agree.

> 
>>
>>   Quick Start
>>    I think we need to keep a top level section called "Quick Start"
>>    because it is easy for a new user to see and click on. The sidebar
>>    on the html output is collapsed and searching for a quick start or
>>    something like it is awkward. Links to other sections should aim to
>>    provide launch sites to more detail.
> 
> Yes, this is now the second chapter. I would like to use the following 
> sections:
> 
> "Host Computer Setup"
> "Prefixes"
> "RTEMS Repository Clone"
> "RTEMS Tool Set Installation"
> "RTEMS Source Bootstrap"
> "BSP Configuration and Installation"
> "Example Application"
> 
> Do we want to use "tool chain" or "tool set" or "tools" for the RTEMS things
> running on the host computer?

Yeah good question. A "tool chain" seems to have a meaning, a compile etc, a
"tool set" is an RSB based term and "tools" is overloaded with the rtems-tools.

I suppose to have a host tool suite? For example, the first sentence from the
Installation section:

 "This section details how to set up and install the RTEMS Ecosystem.
  You will create a tools suite for your host compiler and an RTEMS kernel
  for your selected Board Support Package (BSP)."

> 
>>
>>   Host Computer
>>    Should this be placed under Ecosystem?
>>
>>    This needs to be before the RSB section so the correct packages are
>>    present on the host for the RSB.
> 
> I think this should remain a separate chapter. It is one of the first things 
> you
> have to deal with as a new user.

Sure.

> 
>>
>>   Installation
>>    This explains the environment. Is this also part of the Ecosystem?
> 
> The installation of things running on the host and the installation of an 
> RTEMS
> BSP should be in separate chapters.
> 

Great.

>>
>>   Hardware
>>    A discussion about the way RTEMS views hardware, architectures and
>>    BSPs. This is about the RTEMS side of things rather than the
>>    host and the ecosystem.
>>
>>   Board Support Packages
>>    The BSPs. I have been wondering if the BSP names are suitable
>>    heading or do we want something more formal if that is even
>>    possible?
> 
> The heading is now " ()".
> This should make it easy to find.

Hmm I am not sure, for some reason it looks and feel incomplete, needing more
work because the heading are not formal. For example 'i386' would look better
under Intel.

> 
>>
>>   Executables
>>    This is the first section I have added that starts with something
>>    about the section and what to expect. I think this is a good
>>    practice to do.
>>
>>    I am planning to add a section on libdl and applications for it
>>    once the rtl-archive and rtl-ctor-dtor branches in
>>    https://git.rtems.org/chrisj/rtems.git/ are merged.
>>
>>   Testing
>>    Using the rtems-test and rtems-run interface to run code.
>>
>>   Tracing
>>    The tracing support for RTEMS. This is the last in a progression
>>    from a host, tools, kernel, 

Re: RSB documentation

[Sebastian Huber]

I added a build of the partially restructured user manual here:

https://ftp.rtems.org/pub/rtems/people/sebh/user.pdf

On 13/01/2019 23:03, Chris Johns wrote:

On 11/1/19 8:13 pm, Sebastian Huber wrote:

At which position in the manual should it be placed? I think we should organize 
the chapters according to the relevance for new users and how the are used 
later during application development. I would use the RSB chapter as a 
reference chapter containing all the details and cover the common case in the 
Quick Start chapter. So, I would move the RSB chapter to the end after the Host 
Tools.

The place the RSB moves to could depend on where some others get moved too. A
review of the sections follows.

Do we need a "How to use this manual?" section in the Introduction? It could
also have a "What to read before starting" part.


I think this should go into Introduction -> Overview.



The manual is organised as:

  Introduction
   Overview, features, what a real-time and what a real-time kernel is.

  Ecosystem
   Rational, open source and deployment. This is to explain what we
   call the host side tools, commands, and configuration. Maybe we
   need to explain RTEMS is only run on targets and is not self
   hosting so the ecosystem provides a consistent host side
   environment.

   This section needs to be enhanced to cover the RSB, RTEMS Tools
   and what ever else we want to include. The deployment section's
   building binary tools can be moved to some where else, that is
   an advanced topic.


I moved the Ecosystem into Introduction, since it introduces the RTEMS 
world. I think it fits quite well here.




  Quick Start
   I think we need to keep a top level section called "Quick Start"
   because it is easy for a new user to see and click on. The sidebar
   on the html output is collapsed and searching for a quick start or
   something like it is awkward. Links to other sections should aim to
   provide launch sites to more detail.


Yes, this is now the second chapter. I would like to use the following 
sections:


"Host Computer Setup"
"Prefixes"
"RTEMS Repository Clone"
"RTEMS Tool Set Installation"
"RTEMS Source Bootstrap"
"BSP Configuration and Installation"
"Example Application"

Do we want to use "tool chain" or "tool set" or "tools" for the RTEMS 
things running on the host computer?




  Host Computer
   Should this be placed under Ecosystem?

   This needs to be before the RSB section so the correct packages are
   present on the host for the RSB.


I think this should remain a separate chapter. It is one of the first 
things you have to deal with as a new user.




  Installation
   This explains the environment. Is this also part of the Ecosystem?


The installation of things running on the host and the installation of 
an RTEMS BSP should be in separate chapters.




  Hardware
   A discussion about the way RTEMS views hardware, architectures and
   BSPs. This is about the RTEMS side of things rather than the
   host and the ecosystem.

  Board Support Packages
   The BSPs. I have been wondering if the BSP names are suitable
   heading or do we want something more formal if that is even
   possible?


The heading is now " (name>)". This should make it easy to find.




  Executables
   This is the first section I have added that starts with something
   about the section and what to expect. I think this is a good
   practice to do.

   I am planning to add a section on libdl and applications for it
   once the rtl-archive and rtl-ctor-dtor branches in
   https://git.rtems.org/chrisj/rtems.git/ are merged.

  Testing
   Using the rtems-test and rtems-run interface to run code.

  Tracing
   The tracing support for RTEMS. This is the last in a progression
   from a host, tools, kernel, testing the kernel, to runtime performance.

  Host Tools
   The published interface to the tools we support. In effect the interface
   users can depend on across releases.

I hope this helps.

Note: I see the index is broken with the online builds. I suspect the
genindex.rst removal I did is the cause and I also suspect there is an issue
between versions of sphinx-build being used. My development version is newer
than the online builder but we cannot update that version until the xindy issue
on FreeBSD is resolved and even with upstream FreeBSD fixing the port getting it
into the version 10 we run is problematic.


It is also broken on my host. I use sphinx-build 1.8.1.

--
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: RSB documentation

[Chris Johns]

On 11/1/19 8:13 pm, Sebastian Huber wrote:
> At which position in the manual should it be placed? I think we should 
> organize the chapters according to the relevance for new users and how the 
> are used later during application development. I would use the RSB chapter as 
> a reference chapter containing all the details and cover the common case in 
> the Quick Start chapter. So, I would move the RSB chapter to the end after 
> the Host Tools.

The place the RSB moves to could depend on where some others get moved too. A
review of the sections follows.

Do we need a "How to use this manual?" section in the Introduction? It could
also have a "What to read before starting" part.

The manual is organised as:

 Introduction
  Overview, features, what a real-time and what a real-time kernel is.

 Ecosystem
  Rational, open source and deployment. This is to explain what we
  call the host side tools, commands, and configuration. Maybe we
  need to explain RTEMS is only run on targets and is not self
  hosting so the ecosystem provides a consistent host side
  environment.

  This section needs to be enhanced to cover the RSB, RTEMS Tools
  and what ever else we want to include. The deployment section's
  building binary tools can be moved to some where else, that is
  an advanced topic.

 Quick Start
  I think we need to keep a top level section called "Quick Start"
  because it is easy for a new user to see and click on. The sidebar
  on the html output is collapsed and searching for a quick start or
  something like it is awkward. Links to other sections should aim to
  provide launch sites to more detail.

 Host Computer
  Should this be placed under Ecosystem?

  This needs to be before the RSB section so the correct packages are
  present on the host for the RSB.

 Installation
  This explains the environment. Is this also part of the Ecosystem?

 Hardware
  A discussion about the way RTEMS views hardware, architectures and
  BSPs. This is about the RTEMS side of things rather than the
  host and the ecosystem.

 Board Support Packages
  The BSPs. I have been wondering if the BSP names are suitable
  heading or do we want something more formal if that is even
  possible?

 Executables
  This is the first section I have added that starts with something
  about the section and what to expect. I think this is a good
  practice to do.

  I am planning to add a section on libdl and applications for it
  once the rtl-archive and rtl-ctor-dtor branches in
  https://git.rtems.org/chrisj/rtems.git/ are merged.

 Testing
  Using the rtems-test and rtems-run interface to run code.

 Tracing
  The tracing support for RTEMS. This is the last in a progression
  from a host, tools, kernel, testing the kernel, to runtime performance.

 Host Tools
  The published interface to the tools we support. In effect the interface
  users can depend on across releases.

I hope this helps.

Note: I see the index is broken with the online builds. I suspect the
genindex.rst removal I did is the cause and I also suspect there is an issue
between versions of sphinx-build being used. My development version is newer
than the online builder but we cannot update that version until the xindy issue
on FreeBSD is resolved and even with upstream FreeBSD fixing the port getting it
into the version 10 we run is problematic.

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

Re: RSB documentation

[Sebastian Huber]

- Am 10. Jan 2019 um 0:51 schrieb Chris Johns chr...@rtems.org:

> On 10/1/19 3:41 am, Gedare Bloom wrote:
>> I'm OK with this proposal.  We used to include quite messy details about how 
>> to
>> bootstrap your own GCC in the user manual. This is a bit nicer. ;) At the
>> maturity of RSB now, merging the doco with the User Manual is sensible.
> 
> Agreed, this is sensible. I am fine with this happening.

At which position in the manual should it be placed? I think we should organize 
the chapters according to the relevance for new users and how the are used 
later during application development. I would use the RSB chapter as a 
reference chapter containing all the details and cover the common case in the 
Quick Start chapter. So, I would move the RSB chapter to the end after the Host 
Tools.
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: RSB documentation

[Chris Johns]

On 10/1/19 3:41 am, Gedare Bloom wrote:
> I'm OK with this proposal.  We used to include quite messy details about how 
> to
> bootstrap your own GCC in the user manual. This is a bit nicer. ;) At the
> maturity of RSB now, merging the doco with the User Manual is sensible.

Agreed, this is sensible. I am fine with this happening.

Chris

> 
> On Wed, Jan 9, 2019 at 5:55 AM Sebastian Huber
>  >
> wrote:
> 
> Hello,
> 
> the RSB has currently its own manual in the documentation set:
> 
> https://docs.rtems.org/branches/master/rsb/index.html
> 
> I think it would make sense to move the RSB documentation into the user
> manual as a chapter. If you are new to RTEMS, then dealing with the RSB
> is one of the first things you have to do. I think it is easier if you
> have every to get started in one manual (e.g. you can use documentation
> internal links).
> 
> -- 
> 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
> 
___
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel

Re: RSB documentation

[Gedare Bloom]

I'm OK with this proposal.  We used to include quite messy details about
how to bootstrap your own GCC in the user manual. This is a bit nicer. ;)
At the maturity of RSB now, merging the doco with the User Manual is
sensible.

On Wed, Jan 9, 2019 at 5:55 AM Sebastian Huber <
sebastian.hu...@embedded-brains.de> wrote:

> Hello,
>
> the RSB has currently its own manual in the documentation set:
>
> https://docs.rtems.org/branches/master/rsb/index.html
>
> I think it would make sense to move the RSB documentation into the user
> manual as a chapter. If you are new to RTEMS, then dealing with the RSB
> is one of the first things you have to do. I think it is easier if you
> have every to get started in one manual (e.g. you can use documentation
> internal links).
>
> --
> 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