Please Review Rewrite of Configuring a System Chapter

Tue Apr 9 16:42:39 UTC 2013

On 04/08/2013 07:44 PM, Stephen Tether wrote:
> On 04/06/2013 03:19 PM, Joel Sherrill wrote:
>> Hi
>>
>> I have undertaken a very significant overhaul of the Configuring
>> a System chapter. Each parameter now has a man page style
>> section which allows much greater freedom in including
>> informatin.
> I can only do a few pages for now. I'll try to get more out later this week.
Thanks. All feedback is important.

As a warning, translating these into texinfo changes may have
resulted in mistakes. I am going to merge my branch after
addressing your comments. Patches are easier and safer.

> - Steve Tether
> SLAC National Laboratory
>
> p. 251.
> para. 1: Change "This configuration information" to just "This
> configuration". Insert "kind of" before "RTEMS object".
Got it.
> para. 2: Change "used to RTEMS" to "used by RTEMS". Change "macro based
> system" to "set of macros". Change "the standard and simple" to "a
> simple standard".
Check.
> para. 3: Change "is the core" to "is at the core".
Check.
> para. 5: Change "developer" to "developers".
Check. And verb agreement subsequent.
>   I don't understand
> "standards compliant". Whose standards? RTEMS? POSIX? Maybe here would
> be a good place to mention that RTEMS offers some standard threading
> APIs and that if you configure one of these you must do so in a way
> allowable by the standard.
The Classic API is based on the RTEID/ORKID proposed standards
from VMEBus Industry Trade Association.

I tried to clarify this paragraph. But it is only a bit of text. A full
explanation would end up being a history of RTEMS. :)
>
> para. 6: Please avoid the use of the passive voice. Always say who is
> doing what.
>
> "For each parameter in the configuration tables there is a corresponding
> macro. We (the maintainers of RTEMS) expect that all systems will be
> easily configurable using the <rtems/confdefs.h> mechanism and that
> using it will hide internal RTEMS configuration changes."
Check.

A future pass is to run the manual through languagetool.org.

> para. 7: Change "one application tasks" to "one application task".
Check.
>
> p. 252.
> para. 1: "This calculation includes the amount of memory that will be
> allocated for internal use by RTEMS. The automatic calculation may
> underestimate the workspace size truly needed by the application, in
> which case one can use the CONFIGURE_MEMORY_OVERHEAD macro to add a
> value to the estimate."
I assume that is a replacement for the last two sentences?

I also added a cross-reference to where
CONFIGURE_MEMORY_OVERHEAD is discussed.
>
> para. 2: Insert "and" after "BSP". "Failure to properly align the
> workspace will cause RTEMS initialization code to report a fatal
> RTEMS_INVALID_ADDRESS error."
Interestingly, I think this potential fatal error is no longer
possible to generate. This is handled by shared code in
the BSP.

Separate email to rtems-devel on this.
> para. 3: Replace first sentence with "The file <rtems/confdefs.h> will
> calculate the value of the work_space_size parameter of the
> Configuration Table."
Check.
> para. 4: There's a separate ceiling for each type of object, not a
> single one for the total number of objects.
>
> "For each type of object allocation can be specified in one of two ways.
> The first way allocates space for a fixed number of objects. The second
> way allocates space for an initial number of objects and lets the
> current allocation expand by a fixed increment when required. Both ways
> allocate space inside the RTEMS Workspace."
Check with some mods.
>
> para. 5: "The space needed for stacks and for RTEMS objects will vary
> from one version of RTEMS and from one target processor to another.
> Therefore it's safest to use <rtems/confdefs.h> and specify your
> application's requirements in terms of the numbers of objects and
> multiples of RTEMS_MINIMUM_STACK_SIZE, as far as is possible. The
> automatic estimates of space required will in general change when:
> * a configuration parameter is changed,
> * task or interrupt stack sizes change,
> * the floating point attribute of a task changes,
> * RTEMS is upgraded, or
> * the target processor is changed."
>
Got it.
> In the title for section 23.4 insert "Size" before "Estimation".
>
Got it.
> p. 253.
>
> para. 2: Omit the comma after "reasons" and insert the word "that" instead.
Why was it written that way?

Check.
> para. 4: Insert "of" after "time slice".
Got it and that is the only case of "time slice" in the manual.
It is "timeslice".
>
> First bullet after example: Replace "at" after "execution" by "of a".
Got it.
>
> Second bullet: No, time itself doesn't stop just because you forget to
> configure an RTEMS clock driver! It is RTEMS' internal timekeeping that
> is affected so that the calculated time of day does not advance and
> delays are not executed properly.
How about "Without a clock tick device driver, RTEMS has no way
to know that time is passing and will be unable to support delays
and wall time. "
> p. 254.
>
> para. 2: I believe that this paragraph should say that specifying the
> parameter will make at least one console device, named /dev/console,
> available in the application, and possibly others with different names.
> All of them will support the POSIX termios API. The application's file
> descriptor quota will be made large enough for at least the standard
> three file descriptors for standard input, output and error each of
> which will be mapped to one of the available console devices. For
> example, if there is only /dev/console then all three descriptors will
> be mapped to that device.
I tried. :)

@item By specifying @code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER},
the application will include a console device driver. Although the
console device driver may support a combination of multiple serial
ports and display and keyboard combinations, it is only required to
provide a single device named @code{/dev/console}. This device will
be used for Standard Input, Output and Error I/O Streams. Thus when
@code{CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER} is specified, implicitly
three (3) file descriptors are reserved for the Standard I/O Streams and
those file descriptors are associated with @code{/dev/console} during
initialization. All console devices are expected to support the POSIX
@i{termios} interface.

>
> para. 3: Omit the comma after TASKS. Replace "concurrently existent"
> with "simultaneously existing".
Got it.
> First paragraph in section 23.5.1: I object to the word "deterministic"
> being used in this fashion. In principle the execution of a computer
> program is always determined by its inputs. Using dynamic allocation
> just makes the execution time harder to predict, possibly much harder.
The usage is in keeping with the research literature regarding
Worst-Case Execution Time.

In general, when we say deterministic, we mean O(constant)
independent of the number of object instances.
> _______________________________________________
> rtems-users mailing list
> rtems-users at rtems.org
> http://www.rtems.org/mailman/listinfo/rtems-users

-- 
Joel Sherrill, Ph.D.             Director of Research& Development
joel.sherrill at OARcorp.com        On-Line Applications Research
Ask me about RTEMS: a free RTOS  Huntsville AL 35806
Support Available               (256) 722-9985