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 "<BSP family directory name> (<product marketing name>)".
> 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, 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.

I suspect your texlive has a working xindy which is better than mine. I have
emailed the tex port maintainer and heard nothing back and the tex port lists
seem dormant. The FreeBSD Tex on 12-RELEASE is 2015 and that verison pre-dates
the xindy command. It is a bit of a mess.

Chris