RSB documentation

Chris Johns chrisj at rtems.org
Sun Jan 13 22:03:40 UTC 2019


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



More information about the devel mailing list