Please Review Rewrite of Configuring a System Chapter

[Stephen Tether]

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.

- Steve Tether
SLAC National Laboratory

p. 251.
para. 1: Change "This configuration information" to just "This
configuration". Insert "kind of" before "RTEMS object".

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

para. 3: Change "is the core" to "is at the core".

para. 5: Change "developer" to "developers". 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.

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

para. 7: Change "one application tasks" to "one application task".


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

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

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

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

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


In the title for section 23.4 insert "Size" before "Estimation".


p. 253.

para. 2: Omit the comma after "reasons" and insert the word "that" instead.

para. 4: Insert "of" after "time slice".

First bullet after example: Replace "at" after "execution" by "of a".

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.

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.

para. 3: Omit the comma after TASKS. Replace "concurrently existent"
with "simultaneously existing".

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.